Skip to content
Snippets Groups Projects
Commit 3a16a5a6 authored by Tim Stadtmann's avatar Tim Stadtmann
Browse files

Update documentation for convenience-layer

parent 3d7d0e0e
Branches
Tags
1 merge request!2Develop
Hide whitespace changes
Inline Side-by-side
docs/source.rst
+ 1
− 1
View file @ 3a16a5a6
...@@ -4,7 +4,7 @@ EV3 ...@@ -4,7 +4,7 @@ EV3
--- ---
.. autoclass:: EV3 .. autoclass:: EV3
:members: :members: connect, disconnect, stopAllMotors, beep, playTone, stopTone, tonePlayed, setProperties
Motor Motor
......
source/EV3.m
+ 122
− 128
View file @ 3a16a5a6
...@@ -3,89 +3,110 @@ classdef EV3 < MaskedHandle ...@@ -3,89 +3,110 @@ classdef EV3 < MaskedHandle
% %
% This is the 'central' class (from user's view) when working with this toolbox. It % This is the 'central' class (from user's view) when working with this toolbox. It
% delivers a convenient interface for creating a connection to the brick and sending % delivers a convenient interface for creating a connection to the brick and sending
% commands to it. % commands to it. An EV3-object creates 4 Motor- and 4 Sensor-objects, one for each port.
%
% Notes:
% * Creating multiple EV3 objects and connecting them to different physical bricks has not
% been thoroughly tested yet, but seems to work on a first glance.
% %
% Notes % Attributes:
% * Creating multiple EV3 objects and connecting them to different physical bricks has not % motorA (Motor): Motor-object interfacing port A
% been thoroughly tested yet, but seems to work on a first glance. % motorB (Motor): Motor-object interfacing port B
% * When referring to an instance of this class the term 'virtual brick' is used from now % motorC (Motor): Motor-object interfacing port C
% on. The LEGO EV3 brick itself is referred to as 'physical brick'. % motorD (Motor): Motor-object interfacing port D
% % sensor1 (Sensor): Motor-object interfacing port 1
% Signature % sensor2 (Sensor): Motor-object interfacing port 2
% Author: Tim Stadtmann % sensor3 (Sensor): Motor-object interfacing port 3
% Date: 2016/05/19 % sensor4 (Sensor): Motor-object interfacing port 4
% Updated: 2016/08/15 % debug (numeric in {0,1,2}): Debug mode. [WRITABLE]
% * 0: Debug turned off
% * 1: (High-level-) Debug turned on for EV3-object - enables feedback in the
% console about what firmware-commands have been called when using a method
% * 2: Low-level-Debug turned on - each packet sent and received is printed to the
% console
% batteryMode (string in {'Percentage', 'Voltage'}): Mode for reading battery charge.
% [WRITABLE]
% batteryValue (numeric): Current battery charge. Depending on batteryMode, the reading
% is either in percentage or voltage. [READ-ONLY]
% isConnected (bool): True if virtual brick-object is connected to physical one. [READ-ONLY]
properties % Standard properties properties
%debug - [Writable] Debug turned on or off (0/1/off/on/'false'/'true'/2) % batteryMode (string in {'Percentage', 'Voltage'}): Mode for reading battery charge. [WRITABLE]
% In debug mode 1 (debug=1/'on'/true), everytime a command is passed to the sublayer % See also BATTERYVALUE
% ('communication layer'), there is feedback in the console about what command has been
% called. Debug mode 2 (debug=2) enables debug mode in the lower layers. Each packet
% sent and received is printed to the console.
debug;
%batteryMode - [Writable] Mode for reading battery charge ('Percentage'/'Voltage')
% See also EV3.BATTERYVALUE
batteryMode; batteryMode;
% debug (numeric in {0,1,2}): Debug mode. [WRITABLE]
% * 0: Debug turned off
% * 1: (High-level-) Debug turned on for EV3-object - enables feedback in the
% console about what firmware-commands have been called when using a method
% * 2: Low-level-Debug turned on - each packet sent and received is printed to the
% console
debug;
end end
properties (Dependent) % Parameters to be read directly from physical brick properties (Dependent) % Parameters to be read directly from physical brick
%batteryValue - [Read-only] Current battery charge % batteryValue (numeric): Current battery charge. Depending on batteryMode, the reading
% Depending on batteryMode, the reading is either in percentage or voltage. % is either in percentage or voltage. [READ-ONLY]
% See also EV3.BATTERYMODE
batteryValue; batteryValue;
end end
properties (SetAccess = 'private') % Read-only properties that are set internally properties (SetAccess = private) % Read-only properties that are set internally
%isConnected - [Read-only] Virtual brick connected to physical one? % isConnected (bool): True if virtual brick-object is connected to physical one. [READ-ONLY]
% See also EV3.CONNECT, EV3.DISCONNECT % See also EV3.CONNECT, EV3.DISCONNECT
isConnected = false; isConnected = false;
%motorA - [Read-only] % motorA (Motor): Motor-object interfacing port A
% See also MOTOR % See also MOTOR
motorA; motorA;
%motorB - [Read-only] % motorB (Motor): Motor-object interfacing port B
% See also MOTOR % See also MOTOR
motorB; motorB;
%motorC - [Read-only] % motorC (Motor): Motor-object interfacing port C
% See also MOTOR % See also MOTOR
motorC; motorC;
%motorD - [Read-only] % motorD (Motor): Motor-object interfacing port D
% See also MOTOR % See also MOTOR
motorD; motorD;
%sensor1 - [Read-only] % sensor1 (Sensor): Sensor-object interfacing port 1
% See also SENSOR % See also SENSOR
sensor1; sensor1;
%sensor2 - [Read-only] % sensor2 (Sensor): Sensor-object interfacing port 2
% See also SENSOR % See also SENSOR
sensor2; sensor2;
%sensor3 - [Read-only] % sensor3 (Sensor): Sensor-object interfacing port 3
% See also SENSOR % See also SENSOR
sensor3; sensor3;
%sensor4 - [Read-only] % sensor4 (Sensor): Sensor-object interfacing port 4
% See also SENSOR % See also SENSOR
sensor4; sensor4;
end end
properties (Access = 'private') properties (Access = private)
%commInterface - Interface to communication layer % commInterface (CommunicationInterface): Interface to communication layer
% All commands sent to the Brick are created and written through this object. Each
% Motor- and Sensor-object has a reference to it.
%
commInterface = 0; commInterface = 0;
end end
properties (Hidden, Access = 'private') % Hidden properties for internal use only properties (Hidden, Access = private) % Hidden properties for internal use only
init = true; % Indicates 'init-phase' (Set to 1 as long as constructor is running) % init (bool): Indicates init-phase (i.e. constructor is running).
init = true;
end end
methods % Standard methods methods % Standard methods
%% Constructor %% Constructor
function ev3 = EV3(varargin) function ev3 = EV3(varargin)
%EV3 Sets properties of EV3-object and creates Motor- and Sensor-objects with default % Sets properties of EV3-object and creates Motor- and Sensor-objects with default
% parameters. % parameters.
% %
% Arguments % Arguments
% * varargin: see EV3::setProperties(ev3, varargin) % varargin: see setProperties(ev3, varargin)
% %
% See also SETPROPERTIES
ev3.setProperties(varargin{:}); ev3.setProperties(varargin{:});
...@@ -104,7 +125,7 @@ classdef EV3 < MaskedHandle ...@@ -104,7 +125,7 @@ classdef EV3 < MaskedHandle
end end
function delete(ev3) function delete(ev3)
%delete Disconnects from physical brick and deletes this instance % Disconnects from physical brick and deletes this instance
if ev3.isConnected if ev3.isConnected
ev3.disconnect(); ev3.disconnect();
...@@ -113,16 +134,17 @@ classdef EV3 < MaskedHandle ...@@ -113,16 +134,17 @@ classdef EV3 < MaskedHandle
%% Connection %% Connection
function connect(ev3, varargin) function connect(ev3, varargin)
%connect Connects EV3-object and its Motors and Sensors to physical brick. % Connects EV3-object and its Motors and Sensors to physical brick.
% %
% Arguments % Arguments:
% * 'bt'/'usb': Connection type % connectionType (string in {'bt', 'usb'}): Connection type
% * 'serPort', '/dev/rfcommx': Path to serial port (if 'bt'), where x = 0...9 % serPort (string {'/dev/rfcomm1', '/dev/rfcomm2', ...}): Path to serial port
% * 'beep', bool: EV3 beeps if connection has been established. % (if 'bt')
% beep (bool): If true, EV3 beeps if connection has been established
% %
% Examples % Examples:
% b = EV3(); b.connect('bt', 'serPort', '/dev/rfcomm0'); % b = EV3(); b.connect('bt', 'serPort', '/dev/rfcomm0');
% b = EV3(); b.connect('usb', 'beep', 'on', ); % b = EV3(); b.connect('usb', 'beep', 'on', );
% %
% Check connection % Check connection
...@@ -189,14 +211,16 @@ classdef EV3 < MaskedHandle ...@@ -189,14 +211,16 @@ classdef EV3 < MaskedHandle
end end
function disconnect(ev3) function disconnect(ev3)
%disconnect Disconnects EV3-object and its Motors and Sensors from physical brick. % Disconnects EV3-object and its Motors and Sensors from physical brick.
% %
% Example % Notes:
% b = EV3(); % * Gets called automatically when EV3-object is destroyed.
% b.connect('bt', 'serPort', '/dev/rfcomm0');
% % do stuff
% b.disconnect();
% %
% Example:
% b = EV3();
% b.connect('bt', 'serPort', '/dev/rfcomm0');
% % do stuff
% b.disconnect();
% Reset motors and sensors before disconnecting % Reset motors and sensors before disconnecting
ev3.resetPhysicalBrick(); ev3.resetPhysicalBrick();
...@@ -224,7 +248,7 @@ classdef EV3 < MaskedHandle ...@@ -224,7 +248,7 @@ classdef EV3 < MaskedHandle
%% Device functions %% Device functions
function stopAllMotors(ev3) function stopAllMotors(ev3)
%stopAllMotors Sends a stop-command to all motor-ports % Sends a stop-command to all motor-ports
if ~ev3.isConnected if ~ev3.isConnected
stopAllMotors(['EV3::beep: Brick-Object not connected physical brick. ',... stopAllMotors(['EV3::beep: Brick-Object not connected physical brick. ',...
...@@ -236,15 +260,15 @@ classdef EV3 < MaskedHandle ...@@ -236,15 +260,15 @@ classdef EV3 < MaskedHandle
%% Sound functions %% Sound functions
function beep(ev3) function beep(ev3)
%beep Plays a 'beep' tone on brick. % Plays a 'beep'-tone on brick.
% %
% Notes % Notes:
% * This equals playTone(10, 1000, 100) (Wraps the same opCode in comm-layer) % * This equals playTone(10, 1000, 100) (Wraps the same opCode in comm-layer)
% %
% Example % Example:
% b = EV3(); % b = EV3();
% b.connect('bt', 'serPort', '/dev/rfcomm0'); % b.connect('bt', 'serPort', '/dev/rfcomm0');
% b.beep(); % b.beep();
% %
if ~ev3.isConnected if ~ev3.isConnected
...@@ -260,18 +284,18 @@ classdef EV3 < MaskedHandle ...@@ -260,18 +284,18 @@ classdef EV3 < MaskedHandle
end end
function playTone(ev3, volume, frequency, duration) function playTone(ev3, volume, frequency, duration)
%playTone Plays tone on brick. % Plays tone on brick.
% %
% Arguments % Arguments:
% * volume (0...100) % volume (numeric in [0, 100])
% * frequency (250...10000) % frequency (numeric in [250, 10000])
% * duration (>0, in milliseconds) % duration (numeric >0): in milliseconds
% %
% Example % Example:
% b = EV3(); % b = EV3();
% b.connect('bt', 'serPort', '/dev/rfcomm0'); % b.connect('bt', 'serPort', '/dev/rfcomm0');
% b.playTone(50, 5000, 1000); % Plays tone with 50% volume and 5000Hz for 1 % b.playTone(50, 5000, 1000); % Plays tone with 50% volume and 5000Hz for 1
% % second. % % second.
% %
if ~ev3.isConnected if ~ev3.isConnected
...@@ -287,13 +311,13 @@ classdef EV3 < MaskedHandle ...@@ -287,13 +311,13 @@ classdef EV3 < MaskedHandle
end end
function stopTone(ev3) function stopTone(ev3)
%stopTone Stops tone currently played. % Stops tone currently played
% %
% Example % Example:
% b = EV3(); % b = EV3();
% b.connect('bt', 'serPort', '/dev/rfcomm0'); % b.connect('bt', 'serPort', '/dev/rfcomm0');
% b.playTone(10,100,100000000); % Accidentally given wrong tone duration. % b.playTone(10,100,100000000); % Accidentally given wrong tone duration.
% b.stopTone(); % Stops tone immediately. % b.stopTone(); % Stops tone immediately.
% %
if ~ev3.isConnected if ~ev3.isConnected
...@@ -309,17 +333,17 @@ classdef EV3 < MaskedHandle ...@@ -309,17 +333,17 @@ classdef EV3 < MaskedHandle
end end
function status = tonePlayed(ev3) function status = tonePlayed(ev3)
%tonePlayed Tests if tone is currently played. % Tests if tone is currently played.
%
% Output
% * status: True for a tone being played
% %
% Returns:
% status (bool): True if a tone is being played
%
% Example % Example
% b = EV3(); % b = EV3();
% b.connect('bt', 'serPort', '/dev/rfcomm0'); % b.connect('bt', 'serPort', '/dev/rfcomm0');
% b.playTone(10, 100, 1000); % b.playTone(10, 100, 1000);
% pause(0.5); % pause(0.5);
% b.tonePlayed() -> Outputs 1 to console. % b.tonePlayed() -> Outputs 1 to console.
% %
if ~ev3.isConnected if ~ev3.isConnected
...@@ -365,20 +389,19 @@ classdef EV3 < MaskedHandle ...@@ -365,20 +389,19 @@ classdef EV3 < MaskedHandle
end end
function setProperties(ev3, varargin) function setProperties(ev3, varargin)
%setProperties Set multiple EV3 properties at once using MATLAB's inputParser. % Set multiple EV3 properties at once using MATLAB's inputParser.
% %
% Arguments % Arguments:
% * 'debug', 0/1/'on'/'off'/'true'/'false'/2 % debug (numeric in {0,1,2}): see EV3.debug
% * 'batteryMode', 'Voltage'/'Percentage': Mode in which batteryValue will be read. % batteryMode (string in {'Voltage'/'Percentage'}): see EV3.batteryMode
% %
% Example % Example:
% b = EV3(); % b = EV3();
% b.connect('bt', 'serPort', '/dev/rfcomm0'); % b.connect('bt', 'serPort', '/dev/rfcomm0');
% b.setProperties('debug', 'on', 'batteryMode', 'Voltage'); % b.setProperties('debug', 'on', 'batteryMode', 'Voltage');
% % Instead of: b.debug = 'on'; b.batteryMode = 'Voltage'; % % Instead of: b.debug = 'on'; b.batteryMode = 'Voltage';
% %
% See also EV3.DEBUG, EV3.BATTERYMODE % See also EV3.DEBUG, EV3.BATTERYMODE
%
p = inputParser(); p = inputParser();
...@@ -431,38 +454,9 @@ classdef EV3 < MaskedHandle ...@@ -431,38 +454,9 @@ classdef EV3 < MaskedHandle
end end
warning('on', 'all'); warning('on', 'all');
end end
% function display(ev3)
% warning('off','all');
% %builtin('disp', ev3);
%
%
% props = properties(ev3); % Save list with property names as strings
% fprintf(' <a href="matlab:helpPopup EV3">EV3</a> with properties:\n\n');
% for i = 1:length(props)
% p = props{i};
%
% if isa(ev3.(p), 'handle') && ev3.(p).isvalid % Valid handle?
% if isa(ev3.(p), 'Brick') % Communication interface?
% fprintf('\t%15s: Brick-object (Interface for comm-layer)\n');
% else % Motor or Sensor object?
% fprintf('\t%15s: %s-object for port %s\n', p, class(ev3.(p)), ...
% port2str(class(ev3.(p)), ev3.(p).port));
% end
% elseif isnumeric(ev3.(p))
% fprintf('\t%15s: %d\n', p, ev3.(p));
% elseif ischar(ev3.(p))
% fprintf('\t%15s: %s\n', p, ev3.(p));
% else
% warning('EV3::display: Unsuspected parameter type.'); % Not really useful
% end
% end
%
% warning('on','all');
%
% end
end end
methods (Access = 'private') % Private brick functions that are wrapped by dependent params methods (Access = private) % Private brick functions that are wrapped by dependent params
function bat = getBattery(ev3) function bat = getBattery(ev3)
if ~ev3.isConnected if ~ev3.isConnected
error(['EV3::getBattery: EV3-Object not connected to physical EV3. You have ',... error(['EV3::getBattery: EV3-Object not connected to physical EV3. You have ',...
......
source/Motor.m
+ 61
− 61
View file @ 3a16a5a6
...@@ -6,9 +6,9 @@ classdef Motor < MaskedHandle & dynamicprops ...@@ -6,9 +6,9 @@ classdef Motor < MaskedHandle & dynamicprops
% commands to the brick to be executed on the respective port. % commands to the brick to be executed on the respective port.
% %
% Notes: % Notes:
% * You don't need to create instances of this class. The EV3-class automatically creates % * You don't need to create instances of this class. The EV3-class automatically creates
% instances for each motor port, and you can work with them via the EV3-object. % instances for each motor port, and you can work with them via the EV3-object.
% * The Motor-class represents motor ports, not individual motors! % * The Motor-class represents motor ports, not individual motors!
% %
% Attributes: % Attributes:
% power (numeric in [-100, 100]): Power level of motor in percent. [WRITABLE] % power (numeric in [-100, 100]): Power level of motor in percent. [WRITABLE]
...@@ -167,10 +167,13 @@ classdef Motor < MaskedHandle & dynamicprops ...@@ -167,10 +167,13 @@ classdef Motor < MaskedHandle & dynamicprops
methods % Standard methods methods % Standard methods
%% Constructor %% Constructor
function motor = Motor(varargin) function motor = Motor(varargin)
%Motor Sets properties of Motor-object and indicates end of init-phase when it's done % Sets properties of Motor-object and indicates end of init-phase when it's done.
%
% Notes:
% * input-arguments will directly be handed to Motor.setProperties
% %
% Arguments: % Arguments:
% * varargin: see setProperties(motor, varargin) % varargin: see setProperties(motor, varargin)
% %
motor.setProperties(varargin{:}); motor.setProperties(varargin{:});
...@@ -182,20 +185,20 @@ classdef Motor < MaskedHandle & dynamicprops ...@@ -182,20 +185,20 @@ classdef Motor < MaskedHandle & dynamicprops
% Starts the motor % Starts the motor
% %
% Notes: % Notes:
% * Right now, alternatingly calling this function with and without tacho limit % * Right now, alternatingly calling this function with and without tacho limit
% may lead to unexpected behaviour. For example, if you run the motor without % may lead to unexpected behaviour. For example, if you run the motor without
% a tacholimit for some time using Coast, then stop using Coast, and then try % a tacholimit for some time using Coast, then stop using Coast, and then try
% to run the with a tacholimit, it will stop sooner or later than expected, % to run the with a tacholimit, it will stop sooner or later than expected,
% or may not even start at all. % or may not even start at all.
% * After calling one of the functions to control the motor with some kind of % * After calling one of the functions to control the motor with some kind of
% limit (which is done if limit~=0), the physical brick's power/speed value for % limit (which is done if limit~=0), the physical brick's power/speed value for
% starting without a limit (i.e. if limit==0) is reset to zero. So if you want % starting without a limit (i.e. if limit==0) is reset to zero. So if you want
% to control the motor without a limit after doing so with a limit, you would % to control the motor without a limit after doing so with a limit, you would
% have to set the power manually to the desired value again. (I don't really % have to set the power manually to the desired value again. (I don't really
% know if this is deliberate or a bug, and at this point, I'm too afraid to ask.) % know if this is deliberate or a bug, and at this point, I'm too afraid to ask.)
% To avoid confusion, this is done automatically in this special case. % To avoid confusion, this is done automatically in this special case.
% However, this does not even work all the time. If motor does not % However, this does not even work all the time. If motor does not
% start, call stop() and setPower() manually. :/ % start, call stop() and setPower() manually. :/
% %
% Check connection and if motor is already running % Check connection and if motor is already running
...@@ -348,6 +351,7 @@ classdef Motor < MaskedHandle & dynamicprops ...@@ -348,6 +351,7 @@ classdef Motor < MaskedHandle & dynamicprops
function syncedStart(motor, syncMotor, varargin) function syncedStart(motor, syncMotor, varargin)
% Starts this motor synchronized with another % Starts this motor synchronized with another
%
% This motor acts as a 'master', meaning that the synchronized control is done via % This motor acts as a 'master', meaning that the synchronized control is done via
% this one. When syncedStart is called, the master sets some of the slave's % this one. When syncedStart is called, the master sets some of the slave's
% (syncMotor) properties to keep it consistent with the physical brick. So, for % (syncMotor) properties to keep it consistent with the physical brick. So, for
...@@ -357,18 +361,18 @@ classdef Motor < MaskedHandle & dynamicprops ...@@ -357,18 +361,18 @@ classdef Motor < MaskedHandle & dynamicprops
% limitValue, speedRegulation % limitValue, speedRegulation
% %
% Arguments: % Arguments:
% syncMotor (Motor): the motor-object to sync with % syncMotor (Motor): the motor-object to sync with
% turnRatio (numeric in [-200,200]): Description of turn_ratio (Excerpt of Firmware-comments, in c_output.c): % turnRatio (numeric in [-200,200]): Description of turn_ratio (Excerpt of Firmware-comments, in c_output.c):
% "Turn ratio is how tight you turn and to what direction you turn. [OPTIONAL] % "Turn ratio is how tight you turn and to what direction you turn. [OPTIONAL]
% * 0 value is moving straight forward % * 0 value is moving straight forward
% * Negative values turn to the left % * Negative values turn to the left
% * Positive values turn to the right % * Positive values turn to the right
% * Value -100 stops the left motor % * Value -100 stops the left motor
% * Value +100 stops the right motor % * Value +100 stops the right motor
% * Values less than -100 makes the left motor run the opposite % * Values less than -100 makes the left motor run the opposite
% direction of the right motor (Spin) % direction of the right motor (Spin)
% * Values greater than +100 makes the right motor run the opposite % * Values greater than +100 makes the right motor run the opposite
% direction of the left motor (Spin)" % direction of the left motor (Spin)"
% %
% Notes: % Notes:
% * This is right now a pretty 'heavy' function, as it tests if both motors are % * This is right now a pretty 'heavy' function, as it tests if both motors are
...@@ -378,9 +382,10 @@ classdef Motor < MaskedHandle & dynamicprops ...@@ -378,9 +382,10 @@ classdef Motor < MaskedHandle & dynamicprops
% %
% Example: % Example:
% b = EV3(); b.connect('usb'); % b = EV3(); b.connect('usb');
% m = b.motorA; % m = b.motorA;
% slave = b.motorB;
% m.power = 50; % m.power = 50;
% m.syncedStart(b.motorB); % m.syncedStart(slave);
% % Do stuff % % Do stuff
% m.syncedStop(); % m.syncedStop();
% %
...@@ -476,10 +481,8 @@ classdef Motor < MaskedHandle & dynamicprops ...@@ -476,10 +481,8 @@ classdef Motor < MaskedHandle & dynamicprops
function syncedStop(motor) function syncedStop(motor)
% Stops both motors previously started with syncedStart. % Stops both motors previously started with syncedStart.
% Obviously, if motors have not been started synchronized, this throws an error.
% %
% See also MOTOR.SYNCEDSTART % See also MOTOR.SYNCEDSTART
%
if ~motor.isSynced if ~motor.isSynced
error('Motor::syncedStop: Motor has not been started synchronized with another.'); error('Motor::syncedStop: Motor has not been started synchronized with another.');
...@@ -529,20 +532,19 @@ classdef Motor < MaskedHandle & dynamicprops ...@@ -529,20 +532,19 @@ classdef Motor < MaskedHandle & dynamicprops
% Stops execution of program as long as motor is running % Stops execution of program as long as motor is running
% %
% Notes: % Notes:
% * (OLD)This one's a bit tricky. The opCode OutputReady makes the brick stop sending % * (OLD)This one's a bit tricky. The opCode OutputReady makes the brick stop sending
% responses until the motor has stopped. For security reasons, in this toolbox % responses until the motor has stopped. For security reasons, in this toolbox
% there is an internal timeout for receiving messages from the brick. It raises % there is an internal timeout for receiving messages from the brick. It raises
% an error if a reply takes too long, which would happen in this case. As a % an error if a reply takes too long, which would happen in this case. As a
% workaround, there is an infinite loop that catches errors from outputReady and % workaround, there is an infinite loop that catches errors from outputReady and
% continues then, until outputReady will actually finish without an error. % continues then, until outputReady will actually finish without an error.
% * (OLD)OutputReady (like OutputTest in isRunning) sometimes doesn't work. If % * (OLD)OutputReady (like OutputTest in isRunning) sometimes doesn't work. If
% outputReady returns in less than a second, another while-loop iterates until % outputReady returns in less than a second, another while-loop iterates until
% the motor has stopped, this time using motor.isRunning() (this only works as % the motor has stopped, this time using motor.isRunning() (this only works as
% long as not both OutputTest and OutputReady are buggy). % long as not both OutputTest and OutputReady are buggy).
% * (OLD)Workaround: Poll isRunning (which itself return (speed>0)) until it is false % * (OLD)Workaround: Poll isRunning (which itself return (speed>0)) until it is false
% -> No need to check if motor is connected as speed correctly % (No need to check if motor is connected as speed correctly returns 0 if
% returns 0 if it's not % it's not)
%
if ~motor.connectedToBrick if ~motor.connectedToBrick
error('Motor::waitFor: Motor-Object not connected to comm handle.'); error('Motor::waitFor: Motor-Object not connected to comm handle.');
...@@ -584,8 +586,7 @@ classdef Motor < MaskedHandle & dynamicprops ...@@ -584,8 +586,7 @@ classdef Motor < MaskedHandle & dynamicprops
end end
function internalReset(motor) function internalReset(motor)
% Resets internal tacho count % Resets internal tacho count. Use this if motor behaves weird (i.e. not starting at all, or not correctly
% Use this if motor behaves weird (i.e. not starting at all, or not correctly
% running to limitValue) % running to limitValue)
% %
% The internal tacho count is used for positioning the motor. When the % The internal tacho count is used for positioning the motor. When the
...@@ -595,7 +596,6 @@ classdef Motor < MaskedHandle & dynamicprops ...@@ -595,7 +596,6 @@ classdef Motor < MaskedHandle & dynamicprops
% brakemode is 'Coast', this function is called automatically. % brakemode is 'Coast', this function is called automatically.
% %
% See also MOTOR.RESETTACHOCOUNT % See also MOTOR.RESETTACHOCOUNT
%
if ~motor.connectedToBrick if ~motor.connectedToBrick
error(['Motor::internalReset: Motor-Object not connected to brick handle.',... error(['Motor::internalReset: Motor-Object not connected to brick handle.',...
...@@ -796,15 +796,15 @@ classdef Motor < MaskedHandle & dynamicprops ...@@ -796,15 +796,15 @@ classdef Motor < MaskedHandle & dynamicprops
% Sets multiple Motor properties at once using MATLAB's inputParser. % Sets multiple Motor properties at once using MATLAB's inputParser.
% %
% Arguments: % Arguments:
% debug (bool) % debug (bool) [OPTIONAL]
% smoothStart (numeric in [0, limitValue]) % smoothStart (numeric in [0, limitValue]) [OPTIONAL]
% smoothStop (numeric in [0, limitValue]) % smoothStop (numeric in [0, limitValue]) [OPTIONAL]
% speedRegulation (bool) % speedRegulation (bool) [OPTIONAL]
% brakeMode ('Coast'|'Brake') % brakeMode ('Coast'|'Brake') [OPTIONAL]
% limitMode ('Time'|'Tacho') % limitMode ('Time'|'Tacho') [OPTIONAL]
% limitValue (numeric > 0) % limitValue (numeric > 0) [OPTIONAL]
% power (numeric in [-100,100]) % power (numeric in [-100,100]) [OPTIONAL]
% batteryMode ('Voltage'|'Percentage') % batteryMode ('Voltage'|'Percentage') [OPTIONAL]
% %
% Example: % Example:
% b = EV3(); % b = EV3();
......
source/Sensor.m
+ 77
− 47
View file @ 3a16a5a6
...@@ -9,6 +9,7 @@ classdef Sensor < MaskedHandle ...@@ -9,6 +9,7 @@ classdef Sensor < MaskedHandle
% instances for each sensor port, and you can work with them via the EV3-object. % instances for each sensor port, and you can work with them via the EV3-object.
% * The Sensor-class represents sensor ports, not individual sensors! % * The Sensor-class represents sensor ports, not individual sensors!
% %
%
% Attributes: % Attributes:
% mode (DeviceMode.{Type}): Sensor mode in which the value will be read. By default, % mode (DeviceMode.{Type}): Sensor mode in which the value will be read. By default,
% mode is set to DeviceMode.Default.Undefined. Once a physical sensor is connected % mode is set to DeviceMode.Default.Undefined. Once a physical sensor is connected
...@@ -34,8 +35,9 @@ classdef Sensor < MaskedHandle ...@@ -34,8 +35,9 @@ classdef Sensor < MaskedHandle
% the sublayer ('communication layer'), there is feedback in the console about what % the sublayer ('communication layer'), there is feedback in the console about what
% command has been called. [WRITABLE] % command has been called. [WRITABLE]
% value (numeric): Value read from hysical sensor. What the value represents depends on % value (numeric): Value read from hysical sensor. What the value represents depends on
% sensor.mode. % sensor.mode. [READ-ONLY]
% type (DeviceType): Type of physical sensor connected to the port. Possible types are: [READ-ONLY] % type (DeviceType): Type of physical sensor connected to the port. Possible types are: [READ-ONLY]
%
% * DeviceType.NXTTouch % * DeviceType.NXTTouch
% * DeviceType.NXTLight % * DeviceType.NXTLight
% * DeviceType.NXTSound % * DeviceType.NXTSound
...@@ -54,71 +56,106 @@ classdef Sensor < MaskedHandle ...@@ -54,71 +56,106 @@ classdef Sensor < MaskedHandle
% * DeviceType.Error % * DeviceType.Error
properties % Standard properties to be set by user properties % Standard properties to be set by user
%mode - [Writable] Sensor mode in which the value will be read (DeviceMode.[...]) % mode (DeviceMode.{Type}): Sensor mode in which the value will be read. By default,
% By default, mode is set to DeviceMode.Default.Undefined. The allowed mode (and the % mode is set to DeviceMode.Default.Undefined. Once a physical sensor is connected
% default mode) for a Sensor-object depends on its type. % to the port *and* the physical Brick is connected to the EV3-object, the allowed
% Touch-Sensor: DeviceMode.Touch.Pushed (Default) % mode and the default mode for a Sensor-object are the following (depending on the
% DeviceMode.Touch.Bumps % sensor type): [WRITABLE]
% Ultrasonic-Sensor: DeviceMode.UltraSonic.DistCM (Default) %
% DeviceMode.UltraSonic.DistIn % * Touch-Sensor:
% DeviceMode.UltraSonic.Listen % * DeviceMode.Touch.Pushed [Default]
% Color-Sensor: DeviceMode.Color.Reflect (Default) % * DeviceMode.Touch.Bumps
% DeviceMode.Color.Ambient % * Ultrasonic-Sensor:
% DeviceMode.Color.Col % * DeviceMode.UltraSonic.DistCM [Default]
% Gyro-Sensor: DeviceMode.Gyro.Angular (Default) % * DeviceMode.UltraSonic.DistIn
% DeviceMode.Gyro.Rate % * DeviceMode.UltraSonic.Listen
% * Color-Sensor:
% * DeviceMode.Color.Reflect [Default]
% * DeviceMode.Color.Ambient
% * DeviceMode.Color.Col
% * Gyro-Sensor:
% * DeviceMode.Gyro.Angular [Default]
% * DeviceMode.Gyro.Rate
% %
% See also SENSOR.VALUE, SENSOR.TYPE % See also SENSOR.VALUE, SENSOR.TYPE
mode; mode;
%debug - [Writable] Debug turned on or off (0/1/'on'/'off'/'true'/'false') % debug (bool): Debug turned on or off. In debug mode, everytime a command is passed to
% In debug mode, everytime a command is passed to the sublayer ('communication layer'), % the sublayer ('communication layer'), there is feedback in the console about what
% there is feedback in the console about what command has been called, etc. % command has been called. [WRITABLE]
debug; debug;
end end
properties (Dependent) % Parameters to be read directly from physical brick properties (Dependent) % Parameters to be read directly from physical brick
%value - [Read-only] Value read from sensor % value (numeric): Value read from hysical sensor. What the value represents depends on
% What the value represents depends on sensor.mode. % sensor.mode. [READ-ONLY]
% See also SENSOR.MODE % See also SENSOR.MODE
value; value;
%type - [Read-only] Type of physical sensor connected to port % type (DeviceType): Type of physical sensor connected to the port. Possible types are: [READ-ONLY]
% Entering "DeviceType." + Tab will show you a list of possible types. If virtual brick % * DeviceType.NXTTouch
% is not connected to physical one, type will be DeviceType.Unknown by default. % * DeviceType.NXTLight
% * DeviceType.NXTSound
% * DeviceType.NXTColor
% * DeviceType.NXTUltraSonic
% * DeviceType.NXTTemperature
% * DeviceType.LargeMotor
% * DeviceType.MediumMotor
% * DeviceType.Touch
% * DeviceType.Color
% * DeviceType.UltraSonic
% * DeviceType.Gyro
% * DeviceType.InfraRed
% * DeviceType.Unknown
% * DeviceType.None
% * DeviceType.Error
type; type;
end end
properties (Hidden, Access = private) % Hidden properties for internal use only properties (Hidden, Access = private) % Hidden properties for internal use only
commInterface = 0; % Communication interface % commInterface (CommunicationInterface): Commands are created and sent via the
% communication interface class.
commInterface;
%port - [Read-only] Sensor port ('1'/'2'/'3'/'4') % port (string): Sensor port.
% This is only the string representation of the sensor port to work with. % This is only the string representation of the sensor port to work with.
% Internally, SensorPort-enums are used. % Internally, SensorPort-enums are used.
port; port;
%% Miscallenous flags % init (bool): Indicates init-phase (i.e. constructor is running).
init = true;
connectedToBrick = false; % Does (virtual) sensor-object have a valid brick-handle? % connectedToBrick (bool): True if virtual brick is connected to physical brick.
init = true; % Indicates 'init-phase' (True as long as constructor is running) connectedToBrick = false;
end end
properties (Hidden, Dependent, Access = private) properties (Hidden, Dependent, Access = private)
physicalSensorConnected; % Physical sensor connected to this port? %physicalSensorConnected (bool): True if physical sensor is connected to this port
physicalSensorConnected;
end end
methods % Standard methods methods % Standard methods
%% Constructor %% Constructor
function sensor = Sensor(varargin) function sensor = Sensor(varargin)
% Sets properties of Sensor-object and indicates end of init-phase when it's done
%
% Notes:
% * input-arguments will directly be handed to Motor.setProperties
%
% Arguments:
% varargin: see setProperties(sensor, varargin)
%
sensor.setProperties(varargin{1:end}); sensor.setProperties(varargin{1:end});
sensor.init = false; sensor.init = false;
end end
%% Brick functions %% Brick functions
function reset(sensor) function reset(sensor)
%reset Resets value on sensor % Resets value on sensor
% %
% Note: This clears ALL the sensors right now, no other Op-Code available... :( % Notes:
% * This clears ALL the sensors right now, no other Op-Code available... :(
if ~sensor.connectedToBrick if ~sensor.connectedToBrick
error('Sensor::reset: Sensor-Object not connected to comm handle.'); error('Sensor::reset: Sensor-Object not connected to comm handle.');
elseif ~sensor.physicalSensorConnected elseif ~sensor.physicalSensorConnected
...@@ -185,20 +222,19 @@ classdef Sensor < MaskedHandle ...@@ -185,20 +222,19 @@ classdef Sensor < MaskedHandle
end end
function setProperties(sensor, varargin) function setProperties(sensor, varargin)
%setProperties Sets multiple Sensor properties at once using MATLAB's inputParser. % Sets multiple Sensor properties at once using MATLAB's inputParser.
% %
% Arguments: % Arguments:
% * 'debug', 0/1/'on'/'off'/'true'/'false' % debug (bool) [OPTIONAL]
% * 'mode', DeviceMode.[...] % mode (DeviceMode.{Type}) [OPTIONAL]
% %
% Example: % Example:
% b = EV3(); % b = EV3();
% b.connect('bt', 'serPort', '/dev/rfcomm0'); % b.connect('bt', 'serPort', '/dev/rfcomm0');
% b.sensor1.setProperties('debug', 'on', 'mode', DeviceMode.Color.Ambient); % b.sensor1.setProperties('debug', 'on', 'mode', DeviceMode.Color.Ambient);
% % Instead of: b.sensor1.debug = 'on'; % % Instead of: b.sensor1.debug = 'on';
% % b.sensor1.mode = DeviceMode.Color.Ambient; % % b.sensor1.mode = DeviceMode.Color.Ambient;
% %
p = inputParser(); p = inputParser();
% Set default values % Set default values
...@@ -232,12 +268,6 @@ classdef Sensor < MaskedHandle ...@@ -232,12 +268,6 @@ classdef Sensor < MaskedHandle
function value = get.value(sensor) function value = get.value(sensor)
value = 0; value = 0;
defaultMode = -1; defaultMode = -1;
% if ~isModeValid(sensor.mode, sensor.type)
% warning('Sensor::get.value: Cannot read sensor values in current mode.');
% return;
% elseif strcmp(class(sensor.mode), 'DeviceMode.Default')
% defaultMode = 0;
% end
if sensor.connectedToBrick if sensor.connectedToBrick
value = sensor.getValue(defaultMode); value = sensor.getValue(defaultMode);
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment