Motor.m

classdef Motor < MaskedHandle & dynamicprops      
    % High-level class to work with motors.
    %
    % This class is supposed to ease the use of the brick's motors. It is possible to set all
    % kinds of parameters, request the current status of the motor ports and of course send 
    % 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!
    %     * If you start a motor with power=0, the internal state will still be set to
    %       'isRunning'
    %     * When an input argument of a method is marked as optional, the argument needs to be 
    %       'announced' by a preceding 2nd argument, which is a string containing the name of the argument. 
    %       For example, Motor.setProperties may be given a power-parameter. The syntax would be as
    %       follows: *brickObject.motorA.setProperties('power', 50);*
    %
    % Attributes:
    %    power (numeric in [-100, 100]): Power level of motor in percent. *[WRITABLE]*
    %    speedRegulation (bool): Speed regulation turned on or off. When turned on, motor will 
    %        try to 'hold' its speed at given power level, whatever the load. In this mode, the
    %        highest possible speed depends on the load and mostly goes up to around 70-80 (at 
    %        this point, the Brick internally inputs 100% power). When turned off, motor will 
    %        constantly input the same power into the motor. The resulting speed will be 
    %        somewhat lower, depending on the load. *[WRITABLE]*
    %    smoothStart (numeric s. t. smoothStart+smoothStop < limitValue): Degrees/Time 
    %        indicating how far/long the motor should smoothly start. Depending on limitMode, 
    %        the input is interpreted either in degrees or milliseconds. The first 
    %        {smoothStart}-milliseconds/degrees of limitValue the motor will slowly accelerate 
    %        until reaching its defined speed. See also :attr:`limitValue`, :attr:`limitMode`. *[WRITABLE]*
    %    smoothStop (numeric s. t. smoothStart+smoothStop < limitValue): Degrees/Time 
    %        indicating how far/long the motor should smoothly stop. Depending on limitMode, the 
    %        input is interpreted either in degrees or milliseconds. The last 
    %        [smoothStop]-milliseconds/degrees of limitValue the motor will slowly slow down 
    %        until it has stopped. See also :attr:`limitValue`, :attr:`limitMode`. *[WRITABLE]*
    %    limitValue (numeric>=0): Degrees/Time indicating how far/long the motor should run.
    %        Depending on limitMode, the input is interpreted either in degrees or 
    %        milliseconds. See also :attr:`limitMode`. *[WRITABLE]*
    %    limitMode ('Tacho'|'Time'): Mode for motor limit. See also :attr:`limitValue`. *[WRITABLE]*
    %    brakeMode ('Brake'|'Coast'): Action done when stopping. If 'Coast', the motor will (at 
    %        tacholimit, if ~=0) coast to a stop. If 'Brake', the motor will stop immediately 
    %        (at tacholimit, if ~=0) and hold the brake. *[WRITABLE]*
    %    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]*
    %    isRunning (bool): True if motor is running. *[READ-ONLY]*
    %    tachoCount (numeric): Current tacho count in degrees. *[READ-ONLY]*
    %    currentSpeed (numeric): Current speed of motor. If speedRegulation=on this should equal power, 
    %        otherwise it will probably be lower than that. See also :attr:`speedRegulation`. *[READ-ONLY]*
    %    type (DeviceType): Type of connected device if any. *[READ-ONLY]*
    
    
    properties  % Standard properties to be set by user
        % power (numeric in [-100, 100]): Power level of motor in percent. [WRITABLE]
        power;
        
        % speedRegulation (bool): Speed regulation turned on or off. [WRITABLE]
        %     When turned on, motor will try to 'hold' its speed at given power level, whatever
        %     the load. In this mode, the highest possible speed depends on the load and mostly 
        %     goes up to around 70-80 (at this point, the Brick internally inputs 100% power). 
        %     When turned off, motor will constantly input the same power into the motor. The 
        %     resulting speed will be somewhat lower, depending on the load. 
        speedRegulation;
        
        % smoothStart (numeric s. t. smoothStart+smoothStop < limitValue): Degrees/Time indicating how far/long the motor should smoothly start. [WRITABLE] 
        %     Depending on limitMode, the input is interpreted either in degrees or 
        %     milliseconds. The first {smoothStart}-milliseconds/degrees of limitValue the 
        %     motor will slowly accelerate until reaching its defined speed. 
        % See also MOTOR.LIMITVALUE, MOTOR.LIMITMODE