From 3a16a5a669912f3d2f643e24524ac1eae60cdd65 Mon Sep 17 00:00:00 2001
From: Tim Stadtmann <tim.stadtmann@rwth-aachen.de>
Date: Fri, 2 Dec 2016 14:51:44 +0100
Subject: [PATCH] Update documentation for convenience-layer
---
docs/source.rst | 2 +-
source/EV3.m | 250 +++++++++++++++++++++++-------------------------
source/Motor.m | 122 +++++++++++------------
source/Sensor.m | 124 +++++++++++++++---------
4 files changed, 261 insertions(+), 237 deletions(-)
diff --git a/docs/source.rst b/docs/source.rst
index f5b2873..aec197a 100644
--- a/docs/source.rst
+++ b/docs/source.rst
@@ -4,7 +4,7 @@ EV3
---
.. autoclass:: EV3
- :members:
+ :members: connect, disconnect, stopAllMotors, beep, playTone, stopTone, tonePlayed, setProperties
Motor
diff --git a/source/EV3.m b/source/EV3.m
index d45c42e..d06c335 100755
--- a/source/EV3.m
+++ b/source/EV3.m
@@ -3,89 +3,110 @@ classdef EV3 < MaskedHandle
%
% 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
- % 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
- % * 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.
- % * When referring to an instance of this class the term 'virtual brick' is used from now
- % on. The LEGO EV3 brick itself is referred to as 'physical brick'.
- %
- % Signature
- % Author: Tim Stadtmann
- % Date: 2016/05/19
- % Updated: 2016/08/15
+ % Attributes:
+ % motorA (Motor): Motor-object interfacing port A
+ % motorB (Motor): Motor-object interfacing port B
+ % motorC (Motor): Motor-object interfacing port C
+ % motorD (Motor): Motor-object interfacing port D
+ % sensor1 (Sensor): Motor-object interfacing port 1
+ % sensor2 (Sensor): Motor-object interfacing port 2
+ % sensor3 (Sensor): Motor-object interfacing port 3
+ % sensor4 (Sensor): Motor-object interfacing port 4
+ % 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
- %debug - [Writable] Debug turned on or off (0/1/off/on/'false'/'true'/2)
- % In debug mode 1 (debug=1/'on'/true), everytime a command is passed to the sublayer
- % ('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
+ properties
+ % batteryMode (string in {'Percentage', 'Voltage'}): Mode for reading battery charge. [WRITABLE]
+ % See also BATTERYVALUE
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
properties (Dependent) % Parameters to be read directly from physical brick
- %batteryValue - [Read-only] Current battery charge
- % Depending on batteryMode, the reading is either in percentage or voltage.
- % See also EV3.BATTERYMODE
+ % batteryValue (numeric): Current battery charge. Depending on batteryMode, the reading
+ % is either in percentage or voltage. [READ-ONLY]
batteryValue;
end
- properties (SetAccess = 'private') % Read-only properties that are set internally
- %isConnected - [Read-only] Virtual brick connected to physical one?
+ properties (SetAccess = private) % Read-only properties that are set internally
+ % isConnected (bool): True if virtual brick-object is connected to physical one. [READ-ONLY]
% See also EV3.CONNECT, EV3.DISCONNECT
isConnected = false;
- %motorA - [Read-only]
+ % motorA (Motor): Motor-object interfacing port A
% See also MOTOR
motorA;
- %motorB - [Read-only]
+ % motorB (Motor): Motor-object interfacing port B
% See also MOTOR
motorB;
- %motorC - [Read-only]
+ % motorC (Motor): Motor-object interfacing port C
% See also MOTOR
motorC;
- %motorD - [Read-only]
+ % motorD (Motor): Motor-object interfacing port D
% See also MOTOR
motorD;
- %sensor1 - [Read-only]
+ % sensor1 (Sensor): Sensor-object interfacing port 1
% See also SENSOR
sensor1;
- %sensor2 - [Read-only]
+ % sensor2 (Sensor): Sensor-object interfacing port 2
% See also SENSOR
sensor2;
- %sensor3 - [Read-only]
+ % sensor3 (Sensor): Sensor-object interfacing port 3
% See also SENSOR
sensor3;
- %sensor4 - [Read-only]
+ % sensor4 (Sensor): Sensor-object interfacing port 4
% See also SENSOR
sensor4;
end
- properties (Access = 'private')
- %commInterface - Interface to communication layer
+ properties (Access = private)
+ % 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;
end
- properties (Hidden, Access = 'private') % Hidden properties for internal use only
- init = true; % Indicates 'init-phase' (Set to 1 as long as constructor is running)
+ properties (Hidden, Access = private) % Hidden properties for internal use only
+ % init (bool): Indicates init-phase (i.e. constructor is running).
+ init = true;
end
methods % Standard methods
%% Constructor
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.
%
% Arguments
- % * varargin: see EV3::setProperties(ev3, varargin)
+ % varargin: see setProperties(ev3, varargin)
%
+ % See also SETPROPERTIES
ev3.setProperties(varargin{:});
@@ -104,7 +125,7 @@ classdef EV3 < MaskedHandle
end
function delete(ev3)
- %delete Disconnects from physical brick and deletes this instance
+ % Disconnects from physical brick and deletes this instance
if ev3.isConnected
ev3.disconnect();
@@ -113,16 +134,17 @@ classdef EV3 < MaskedHandle
%% Connection
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
- % * 'bt'/'usb': Connection type
- % * 'serPort', '/dev/rfcommx': Path to serial port (if 'bt'), where x = 0...9
- % * 'beep', bool: EV3 beeps if connection has been established.
+ % Arguments:
+ % connectionType (string in {'bt', 'usb'}): Connection type
+ % serPort (string {'/dev/rfcomm1', '/dev/rfcomm2', ...}): Path to serial port
+ % (if 'bt')
+ % beep (bool): If true, EV3 beeps if connection has been established
%
- % Examples
- % b = EV3(); b.connect('bt', 'serPort', '/dev/rfcomm0');
- % b = EV3(); b.connect('usb', 'beep', 'on', );
+ % Examples:
+ % b = EV3(); b.connect('bt', 'serPort', '/dev/rfcomm0');
+ % b = EV3(); b.connect('usb', 'beep', 'on', );
%
% Check connection
@@ -189,14 +211,16 @@ classdef EV3 < MaskedHandle
end
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
- % b = EV3();
- % b.connect('bt', 'serPort', '/dev/rfcomm0');
- % % do stuff
- % b.disconnect();
+ % Notes:
+ % * Gets called automatically when EV3-object is destroyed.
%
+ % Example:
+ % b = EV3();
+ % b.connect('bt', 'serPort', '/dev/rfcomm0');
+ % % do stuff
+ % b.disconnect();
% Reset motors and sensors before disconnecting
ev3.resetPhysicalBrick();
@@ -224,7 +248,7 @@ classdef EV3 < MaskedHandle
%% Device functions
function stopAllMotors(ev3)
- %stopAllMotors Sends a stop-command to all motor-ports
+ % Sends a stop-command to all motor-ports
if ~ev3.isConnected
stopAllMotors(['EV3::beep: Brick-Object not connected physical brick. ',...
@@ -236,15 +260,15 @@ classdef EV3 < MaskedHandle
%% Sound functions
function beep(ev3)
- %beep Plays a 'beep' tone on brick.
+ % Plays a 'beep'-tone on brick.
%
- % Notes
- % * This equals playTone(10, 1000, 100) (Wraps the same opCode in comm-layer)
+ % Notes:
+ % * This equals playTone(10, 1000, 100) (Wraps the same opCode in comm-layer)
%
- % Example
- % b = EV3();
- % b.connect('bt', 'serPort', '/dev/rfcomm0');
- % b.beep();
+ % Example:
+ % b = EV3();
+ % b.connect('bt', 'serPort', '/dev/rfcomm0');
+ % b.beep();
%
if ~ev3.isConnected
@@ -260,18 +284,18 @@ classdef EV3 < MaskedHandle
end
function playTone(ev3, volume, frequency, duration)
- %playTone Plays tone on brick.
+ % Plays tone on brick.
%
- % Arguments
- % * volume (0...100)
- % * frequency (250...10000)
- % * duration (>0, in milliseconds)
+ % Arguments:
+ % volume (numeric in [0, 100])
+ % frequency (numeric in [250, 10000])
+ % duration (numeric >0): in milliseconds
%
- % Example
- % b = EV3();
- % b.connect('bt', 'serPort', '/dev/rfcomm0');
- % b.playTone(50, 5000, 1000); % Plays tone with 50% volume and 5000Hz for 1
- % % second.
+ % Example:
+ % b = EV3();
+ % b.connect('bt', 'serPort', '/dev/rfcomm0');
+ % b.playTone(50, 5000, 1000); % Plays tone with 50% volume and 5000Hz for 1
+ % % second.
%
if ~ev3.isConnected
@@ -287,13 +311,13 @@ classdef EV3 < MaskedHandle
end
function stopTone(ev3)
- %stopTone Stops tone currently played.
+ % Stops tone currently played
%
- % Example
- % b = EV3();
- % b.connect('bt', 'serPort', '/dev/rfcomm0');
- % b.playTone(10,100,100000000); % Accidentally given wrong tone duration.
- % b.stopTone(); % Stops tone immediately.
+ % Example:
+ % b = EV3();
+ % b.connect('bt', 'serPort', '/dev/rfcomm0');
+ % b.playTone(10,100,100000000); % Accidentally given wrong tone duration.
+ % b.stopTone(); % Stops tone immediately.
%
if ~ev3.isConnected
@@ -309,17 +333,17 @@ classdef EV3 < MaskedHandle
end
function status = tonePlayed(ev3)
- %tonePlayed Tests if tone is currently played.
- %
- % Output
- % * status: True for a tone being played
+ % Tests if tone is currently played.
%
+ % Returns:
+ % status (bool): True if a tone is being played
+ %
% Example
- % b = EV3();
- % b.connect('bt', 'serPort', '/dev/rfcomm0');
- % b.playTone(10, 100, 1000);
- % pause(0.5);
- % b.tonePlayed() -> Outputs 1 to console.
+ % b = EV3();
+ % b.connect('bt', 'serPort', '/dev/rfcomm0');
+ % b.playTone(10, 100, 1000);
+ % pause(0.5);
+ % b.tonePlayed() -> Outputs 1 to console.
%
if ~ev3.isConnected
@@ -365,20 +389,19 @@ classdef EV3 < MaskedHandle
end
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
- % * 'debug', 0/1/'on'/'off'/'true'/'false'/2
- % * 'batteryMode', 'Voltage'/'Percentage': Mode in which batteryValue will be read.
+ % Arguments:
+ % debug (numeric in {0,1,2}): see EV3.debug
+ % batteryMode (string in {'Voltage'/'Percentage'}): see EV3.batteryMode
%
- % Example
- % b = EV3();
- % b.connect('bt', 'serPort', '/dev/rfcomm0');
- % b.setProperties('debug', 'on', 'batteryMode', 'Voltage');
- % % Instead of: b.debug = 'on'; b.batteryMode = 'Voltage';
+ % Example:
+ % b = EV3();
+ % b.connect('bt', 'serPort', '/dev/rfcomm0');
+ % b.setProperties('debug', 'on', 'batteryMode', 'Voltage');
+ % % Instead of: b.debug = 'on'; b.batteryMode = 'Voltage';
%
% See also EV3.DEBUG, EV3.BATTERYMODE
- %
p = inputParser();
@@ -431,38 +454,9 @@ classdef EV3 < MaskedHandle
end
warning('on', 'all');
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
- 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)
if ~ev3.isConnected
error(['EV3::getBattery: EV3-Object not connected to physical EV3. You have ',...
diff --git a/source/Motor.m b/source/Motor.m
index c96276c..4c1572c 100755
--- a/source/Motor.m
+++ b/source/Motor.m
@@ -6,9 +6,9 @@ classdef Motor < MaskedHandle & dynamicprops
% commands to the brick to be executed on the respective port.
%
% Notes:
- % * 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.
- % * The Motor-class represents motor ports, not individual motors!
+ % * 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.
+ % * The Motor-class represents motor ports, not individual motors!
%
% Attributes:
% power (numeric in [-100, 100]): Power level of motor in percent. [WRITABLE]
@@ -167,10 +167,13 @@ classdef Motor < MaskedHandle & dynamicprops
methods % Standard methods
%% Constructor
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:
- % * varargin: see setProperties(motor, varargin)
+ % varargin: see setProperties(motor, varargin)
%
motor.setProperties(varargin{:});
@@ -182,20 +185,20 @@ classdef Motor < MaskedHandle & dynamicprops
% Starts the motor
%
% Notes:
- % * Right now, alternatingly calling this function with and without tacho limit
- % 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
- % to run the with a tacholimit, it will stop sooner or later than expected,
- % or may not even start at all.
- % * 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
- % 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
- % 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.)
- % To avoid confusion, this is done automatically in this special case.
- % However, this does not even work all the time. If motor does not
- % start, call stop() and setPower() manually. :/
+ % * Right now, alternatingly calling this function with and without tacho limit
+ % 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
+ % to run the with a tacholimit, it will stop sooner or later than expected,
+ % or may not even start at all.
+ % * 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
+ % 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
+ % 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.)
+ % To avoid confusion, this is done automatically in this special case.
+ % However, this does not even work all the time. If motor does not
+ % start, call stop() and setPower() manually. :/
%
% Check connection and if motor is already running
@@ -348,6 +351,7 @@ classdef Motor < MaskedHandle & dynamicprops
function syncedStart(motor, syncMotor, varargin)
% Starts this motor synchronized with another
+ %
% 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
% (syncMotor) properties to keep it consistent with the physical brick. So, for
@@ -357,18 +361,18 @@ classdef Motor < MaskedHandle & dynamicprops
% limitValue, speedRegulation
%
% Arguments:
- % 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):
- % "Turn ratio is how tight you turn and to what direction you turn. [OPTIONAL]
- % * 0 value is moving straight forward
- % * Negative values turn to the left
- % * Positive values turn to the right
- % * Value -100 stops the left motor
- % * Value +100 stops the right motor
- % * Values less than -100 makes the left motor run the opposite
- % direction of the right motor (Spin)
- % * Values greater than +100 makes the right motor run the opposite
- % direction of the left motor (Spin)"
+ % 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):
+ % "Turn ratio is how tight you turn and to what direction you turn. [OPTIONAL]
+ % * 0 value is moving straight forward
+ % * Negative values turn to the left
+ % * Positive values turn to the right
+ % * Value -100 stops the left motor
+ % * Value +100 stops the right motor
+ % * Values less than -100 makes the left motor run the opposite
+ % direction of the right motor (Spin)
+ % * Values greater than +100 makes the right motor run the opposite
+ % direction of the left motor (Spin)"
%
% Notes:
% * This is right now a pretty 'heavy' function, as it tests if both motors are
@@ -378,9 +382,10 @@ classdef Motor < MaskedHandle & dynamicprops
%
% Example:
% b = EV3(); b.connect('usb');
- % m = b.motorA;
+ % m = b.motorA;
+ % slave = b.motorB;
% m.power = 50;
- % m.syncedStart(b.motorB);
+ % m.syncedStart(slave);
% % Do stuff
% m.syncedStop();
%
@@ -476,10 +481,8 @@ classdef Motor < MaskedHandle & dynamicprops
function syncedStop(motor)
% Stops both motors previously started with syncedStart.
- % Obviously, if motors have not been started synchronized, this throws an error.
%
% See also MOTOR.SYNCEDSTART
- %
if ~motor.isSynced
error('Motor::syncedStop: Motor has not been started synchronized with another.');
@@ -529,20 +532,19 @@ classdef Motor < MaskedHandle & dynamicprops
% Stops execution of program as long as motor is running
%
% Notes:
- % * (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
- % 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
- % workaround, there is an infinite loop that catches errors from outputReady and
- % continues then, until outputReady will actually finish without an error.
- % * (OLD)OutputReady (like OutputTest in isRunning) sometimes doesn't work. If
- % 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
- % long as not both OutputTest and OutputReady are buggy).
- % * (OLD)Workaround: Poll isRunning (which itself return (speed>0)) until it is false
- % -> No need to check if motor is connected as speed correctly
- % returns 0 if it's not
- %
+ % * (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
+ % 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
+ % workaround, there is an infinite loop that catches errors from outputReady and
+ % continues then, until outputReady will actually finish without an error.
+ % * (OLD)OutputReady (like OutputTest in isRunning) sometimes doesn't work. If
+ % 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
+ % long as not both OutputTest and OutputReady are buggy).
+ % * (OLD)Workaround: Poll isRunning (which itself return (speed>0)) until it is false
+ % (No need to check if motor is connected as speed correctly returns 0 if
+ % it's not)
if ~motor.connectedToBrick
error('Motor::waitFor: Motor-Object not connected to comm handle.');
@@ -584,8 +586,7 @@ classdef Motor < MaskedHandle & dynamicprops
end
function internalReset(motor)
- % Resets internal tacho count
- % Use this if motor behaves weird (i.e. not starting at all, or not correctly
+ % Resets internal tacho count. Use this if motor behaves weird (i.e. not starting at all, or not correctly
% running to limitValue)
%
% The internal tacho count is used for positioning the motor. When the
@@ -595,7 +596,6 @@ classdef Motor < MaskedHandle & dynamicprops
% brakemode is 'Coast', this function is called automatically.
%
% See also MOTOR.RESETTACHOCOUNT
- %
if ~motor.connectedToBrick
error(['Motor::internalReset: Motor-Object not connected to brick handle.',...
@@ -796,15 +796,15 @@ classdef Motor < MaskedHandle & dynamicprops
% Sets multiple Motor properties at once using MATLAB's inputParser.
%
% Arguments:
- % debug (bool)
- % smoothStart (numeric in [0, limitValue])
- % smoothStop (numeric in [0, limitValue])
- % speedRegulation (bool)
- % brakeMode ('Coast'|'Brake')
- % limitMode ('Time'|'Tacho')
- % limitValue (numeric > 0)
- % power (numeric in [-100,100])
- % batteryMode ('Voltage'|'Percentage')
+ % debug (bool) [OPTIONAL]
+ % smoothStart (numeric in [0, limitValue]) [OPTIONAL]
+ % smoothStop (numeric in [0, limitValue]) [OPTIONAL]
+ % speedRegulation (bool) [OPTIONAL]
+ % brakeMode ('Coast'|'Brake') [OPTIONAL]
+ % limitMode ('Time'|'Tacho') [OPTIONAL]
+ % limitValue (numeric > 0) [OPTIONAL]
+ % power (numeric in [-100,100]) [OPTIONAL]
+ % batteryMode ('Voltage'|'Percentage') [OPTIONAL]
%
% Example:
% b = EV3();
diff --git a/source/Sensor.m b/source/Sensor.m
index 59132ec..3082f40 100755
--- a/source/Sensor.m
+++ b/source/Sensor.m
@@ -9,6 +9,7 @@ classdef Sensor < MaskedHandle
% instances for each sensor port, and you can work with them via the EV3-object.
% * The Sensor-class represents sensor ports, not individual sensors!
%
+ %
% Attributes:
% 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
@@ -34,8 +35,9 @@ classdef Sensor < MaskedHandle
% the sublayer ('communication layer'), there is feedback in the console about what
% command has been called. [WRITABLE]
% 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]
+ %
% * DeviceType.NXTTouch
% * DeviceType.NXTLight
% * DeviceType.NXTSound
@@ -54,71 +56,106 @@ classdef Sensor < MaskedHandle
% * DeviceType.Error
properties % Standard properties to be set by user
- %mode - [Writable] Sensor mode in which the value will be read (DeviceMode.[...])
- % By default, mode is set to DeviceMode.Default.Undefined. The allowed mode (and the
- % default mode) for a Sensor-object depends on its type.
- % Touch-Sensor: DeviceMode.Touch.Pushed (Default)
- % DeviceMode.Touch.Bumps
- % Ultrasonic-Sensor: DeviceMode.UltraSonic.DistCM (Default)
- % DeviceMode.UltraSonic.DistIn
- % DeviceMode.UltraSonic.Listen
- % Color-Sensor: DeviceMode.Color.Reflect (Default)
- % DeviceMode.Color.Ambient
- % DeviceMode.Color.Col
- % Gyro-Sensor: DeviceMode.Gyro.Angular (Default)
- % DeviceMode.Gyro.Rate
+ % 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
+ % to the port *and* the physical Brick is connected to the EV3-object, the allowed
+ % mode and the default mode for a Sensor-object are the following (depending on the
+ % sensor type): [WRITABLE]
+ %
+ % * Touch-Sensor:
+ % * DeviceMode.Touch.Pushed [Default]
+ % * DeviceMode.Touch.Bumps
+ % * Ultrasonic-Sensor:
+ % * DeviceMode.UltraSonic.DistCM [Default]
+ % * DeviceMode.UltraSonic.DistIn
+ % * 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
mode;
- %debug - [Writable] Debug turned on or off (0/1/'on'/'off'/'true'/'false')
- % In debug mode, everytime a command is passed to the sublayer ('communication layer'),
- % there is feedback in the console about what command has been called, etc.
+ % debug (bool): Debug turned on or off. In debug mode, everytime a command is passed to
+ % the sublayer ('communication layer'), there is feedback in the console about what
+ % command has been called. [WRITABLE]
debug;
end
properties (Dependent) % Parameters to be read directly from physical brick
- %value - [Read-only] Value read from sensor
- % What the value represents depends on sensor.mode.
+ % value (numeric): Value read from hysical sensor. What the value represents depends on
+ % sensor.mode. [READ-ONLY]
% See also SENSOR.MODE
value;
- %type - [Read-only] Type of physical sensor connected to port
- % Entering "DeviceType." + Tab will show you a list of possible types. If virtual brick
- % is not connected to physical one, type will be DeviceType.Unknown by default.
+ % type (DeviceType): Type of physical sensor connected to the port. Possible types are: [READ-ONLY]
+ % * DeviceType.NXTTouch
+ % * 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;
end
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')
- % This is only the string representation of the sensor port to work with.
- % Internally, SensorPort-enums are used.
+ % port (string): Sensor port.
+ % This is only the string representation of the sensor port to work with.
+ % Internally, SensorPort-enums are used.
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?
- init = true; % Indicates 'init-phase' (True as long as constructor is running)
+ % connectedToBrick (bool): True if virtual brick is connected to physical brick.
+ connectedToBrick = false;
end
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
methods % Standard methods
%% Constructor
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.init = false;
end
%% Brick functions
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
error('Sensor::reset: Sensor-Object not connected to comm handle.');
elseif ~sensor.physicalSensorConnected
@@ -185,20 +222,19 @@ classdef Sensor < MaskedHandle
end
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:
- % * 'debug', 0/1/'on'/'off'/'true'/'false'
- % * 'mode', DeviceMode.[...]
+ % debug (bool) [OPTIONAL]
+ % mode (DeviceMode.{Type}) [OPTIONAL]
%
% Example:
- % b = EV3();
- % b.connect('bt', 'serPort', '/dev/rfcomm0');
- % b.sensor1.setProperties('debug', 'on', 'mode', DeviceMode.Color.Ambient);
- % % Instead of: b.sensor1.debug = 'on';
- % % b.sensor1.mode = DeviceMode.Color.Ambient;
+ % b = EV3();
+ % b.connect('bt', 'serPort', '/dev/rfcomm0');
+ % b.sensor1.setProperties('debug', 'on', 'mode', DeviceMode.Color.Ambient);
+ % % Instead of: b.sensor1.debug = 'on';
+ % % b.sensor1.mode = DeviceMode.Color.Ambient;
%
-
p = inputParser();
% Set default values
@@ -232,12 +268,6 @@ classdef Sensor < MaskedHandle
function value = get.value(sensor)
value = 0;
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
value = sensor.getValue(defaultMode);
--
GitLab