Direct NXT commands

In this final chapter we only list some more examples and commands. Usually they aren't needed in the daily life of a MATLAB Mindstorms NXT programmer.

Contents

All functions beginning with NXT_ are basically just ported from the official LEGO NXT Bluetooth Protocol and Direct Commands documentation (download Bluetooth Developer Kit from LEGO).

We just list some examples and commands...

Keep alive and battery level

To keep the NXT from turning off automatically, send a keep-alive packet from time to time (if needed):

NXT_SendKeepAlive('dontreply');

If you're interested in the internal sleep time limit setting, just request it:

[status SleepTimeLimit] = NXT_SendKeepAlive('reply');

% To see after how many minutes the NXT will shut down:
minutes = SleepTimeLimit / 1000 / 60;

So how much energy does my bot have left?

voltage = NXT_GetBatteryLevel;

% actually, the unit is milli volts, so
voltage = voltage / 1000; % :-)

Every function that retrieves (i.e. "gets") values from the NXT is internally split into two parts. But this doesn't have to concern you right now. Note how we called the functions without passing a blutooth handle - we simply set the default handle at the beginning of our program or session.

Important direct commands

These are the interesting ones. The list is not complete however!

This section only covers the syntax, for details what the functions do please consider the official LEGO documentation or the function help.

% frequency is in Hz, duration in ms
NXT_PlayTone(frequency, duration);
% the common way would be this
NXT_SetInputMode(InputPort, SensorTypeDesc, SensorModeDesc, 'dontreply');

% but if you want an acknowledgement (usually not needed), then use
status = NXT_SetInputMode(InputPort, SensorTypeDesc, SensorModeDesc, 'reply');
% note: the statusbyte will be automatically checked anyway (and a warning
% issued if necessary), but you can still check the status now to handle the
% consequences properly...
NXT_ResetInputScaledValue(port);
% in this function there is no way to request an acknowledgement...
% only call this after you've set a proper input mode
data = NXT_GetInputValues(port);

% simple function, heavy output:

out.Port            % from what port
out.Valid           % is this sensorreading valid? if not, well... discard?
out.Calibrated      % for future use of NXT firmware
out.TypeByte        % sensor type
out.TypeName        % sensor type, but human readable
out.ModeByte        % sensor mode
out.ModeName        % sensor mode, human readable
out.RawADVal        % raw digital value, do nut use
out.NormalizedADVal % use THIS, normalized value, 10bits, between 0 and 1023
out.ScaledVal       % use this, depends on the input mode you set
out.CalibratedVal   % for future use of NXT firmware
% Notation as seen in the Direct Commands doc:
% true = relative = BlockTachoCount, false = absolute = RotationCount
NXT_ResetMotorPosition(port, true);
% more lines for better readability
NXT_SetOutputState(whatmotor, ... % port
    20, ...         % power
    true, ...       % motoron?
    true, ...       % brake?
    'SPEED', ...    % regulation
    0, ...          % turnratio
    'RUNNING', ...  % runstate
    0, ...          % tacho limit (0 = forever)
    'dontreply');   % replymode
out = NXT_GetOutputState(port);

% just like with GetInputValues: simple call, complex output:

out.Port                % motornumber
out.Power               % power
out.Mode                % complete mode-byte (bitfield), see below for easier usage
out.ModeIsMOTORON       % boolean, state of MOTORON bit (false means motor has no power)
out.ModeIsBRAKE         % boolean, state of electronic braking (improves motor performance)
out.ModeIsREGULATED     % boolean, if set, see RegModeName, if not set, reg mode will be IDLE
out.RegModeByte         % regulation mode, binary
out.RegModeName         % name of regulation mode: IDLE, SPEED, or SYNC
out.TurnRatio           % turn ratio, 0 = straight forward
out.RunStateByte        % run state, binary
out.RunStateName        % name of run state: IDLE, RUNNING, RAMPUP or RAMPDOWN
out.TachoLimit          % current tacho limit (we'll call it AngleLimit later on)
out.TachoCount          % TachoCount = internal cumulative motor-degree-counter.
out.BlockTachoCount     % motor-degree-counter, resettable using "ResetMotorPosition relative"
out.RotationCount       % motor-degree-counter, resettable using "ResetMotorPosition absolute"

To execute "real" Mindstorms programs on the NXT (i.e. programs that you created using the official LEGO software and stored it locally on the NXT), you can call this function:

NXT_StartProgram('MyDemo.rxe');
% the file extension '.rxe' can be omitted, it will then be automatically added

Stopping the currently running program can be accomplished with

NXT_StopProgram();

There are three more NXT direct commands: NXT_LSGetStatus, NXT_LSWrite, NXT_LSRead. They all have one purpose: Address digital sensors that use the I²C-Protocol. An example is the ultrasonic sensor, and for more documentation you might want to see the sourcecode of OpenUltrasonic and GetUltrasonic.

The idea is to send data (containing I²C payload) first with NXT_LSWrite. Then check the sensor status in a loop using NXT_LSGetStatus until it is ready, i.e. until the status byte reports no error and all requested bytes are available. Those bytes can then be received using NXT_LSRead.