RWTH - Mindstorms NXT Toolbox Version 2.00 Guidelines

This document describes the main changes in version 2.00 this toolbox and gives a short introduction on how to use them!

Contents

The communication layer

To establish a connection to an NXT device, the following functions are provided:

They replace the old BT_ functions from toolbox version 1.00. Also BT_CreatePacket, BT_SendPacket, and BT_CollectPacket have been replaced by COM_CreatePacket, COM_SendPacket, and COM_CollectPacket. These changes are only to be consistent with the naming scheme, the usage of these functions has not changed. The prefix COM_ stands for "communication functions".

The most important change in toolbox version 2.00 is the support for USB connections. On Windows systems, the Mindstorms NXT device driver (called "Fantom") has to be installed. On Linux systems, the free open source library libusb is used. Additionally, the devices' access rights have to be modified so that the NXT bricks appear in /dev/.

Opening connections and retrieving handles

The following way is recommended to open a connection:

h = COM_OpenNXT('bluetooth.ini');
COM_SetDefaultNXT(h);

This replaces what looked like this in toolbox version 1.00:

h = BT_OpenHandle('bluetooth.ini');
BT_SetDefaultHandle(h);

The big difference however is that COM_OpenNXT will also look on the USB bus for an NXT. If it succeeds, the USB connection will be used, otherwise a Bluetooth connection is created. This makes the above example work with both Bluetooth and USB connections without having to change the code! Just plug or unplug the USB cable to your NXT device. If USB is present, it will be used, if not, Bluetooth comes into action.

The handle struct

In version 1.00 our NXT handle was just a variable (serial object on Windows, file handle on Linux). Now, we have a fairly large struct, containing lots of useful (and necessary) information. The users do NOT have to use this handle in any way but to pass it to functions, just as they could in earlier versions. All other functions and commands just work as they did before!

The handle contains some function-handles (to store dynamic information using the principle of function closures). However they are not to be used by normal users! It will later be explained to the advanced user how to retrieve connection statistics (how many bytes and packets were sent or received).

For now, the message is: We have got a huge handle struct, look at it if you want, but do not modify it. It does not matter what is in there, everything just works, so no need to bother!

Default handles

To put it simply: BT_SetDefaultHandle and BT_GetDefaultHandle have just been replaced by COM_SetDefaultNXT and COM_GetDefaultNXT. So adapt your code, the syntax is exactly the same.

Closing handles and cleaning up

The two functions BT_CloseHandle and BT_CloseAllHandles have been combined to the one function COM_CloseNXT.

To clean up after using your NXT-handle, just call

COM_CloseNXT(h);
clear h % this is not necessary but good practice, so I recommend it

Instead of BT_CloseAllHandles we now have:

COM_CloseNXT all

The old way of closing just a specific serial port has been mapped to this syntax:

COM_CloseNXT('all', 'bluetooth.ini');

New debug functions

The way the function textOut behaves has not changed. But it was quite uncomfortable to use global DisableScreenOut in order to enable or disable debug messages. So we now have helper functions:

DebugMode on
    % do something
DebugMode off

DebugMode(state) is a method that can set the debug-state, but when called without any arguments, DebugMode() will return the current setting. So if we want to remember and restore the previous state, we can do so by:

OldDebugState = DebugMode(); % remember old state
DebugMode on  % force it to always be on
    % do something with guaranteed debug infos
DebugMode(OldDebugState); % be polite, reset to old state

To check if debug messages are enabled, use:

if isdebug
    % we know debug mode is set to 'on'
end%if

This is essentially the same as

if strcmpi(DebugMode(), 'on')
    % we know debug mode is set to 'on'
end%if

but since MATLAB is not very fast with string comparisons, I recommend to use isdebug where time is critical. Also it is easier.

Please note the similarity to MATLAB's built-in functions hold on, hold off and ishold.

New "snapshot" mode for ultrasonic sensor

The function OpenUltrasonic has been updated with the additional optional parameter 'snapshot'. When set, the functions USMakeSnapshot and USGetSnapshotResults enable you to send out a single "ping" signal, and let the sensor record up to 8 following echos. All 8 recordings can then be retrieved in one step. See function help for further information. An example might look like this:

port = SENSOR_4;
OpenUltrasonic(port, 'snapshot');
% send out the ping
USMakeSnapshot(port);
% wait some time for the sound to travel
pause(0.1); % 100ms is probably too much, calculate using c_sound ;-)
% retrieve all the echos in 1 step
echos = USGetSnapshotResults(port);
CloseSensor(port);

New I/O Map Module access

New system functions NXT_ReadIOMap and NXT_WriteIOMap have been implemented, enabling low-level access to the NXT's internal I/O map module registers. For easier usage, some high level functions have been implemented. They all start with the prefix MAP_, see list of functions and their documentation for further information.

Note: These new functions do not (yet?) work under Windows when using USB connections. They do however work with Bluetooth under Windows. On Linux systems, both USB and Bluetooth connections are supported for I/O map module access.

Conclusion

To sum up all necessary changes for your programs:

Contact

Please feel free to contact me by mail if you have comments:

linus (dot) atorf (at) rwth-aachen (dot) de

or via http://www.mindstorms.rwth-aachen.de

Version 1.01 of this document, Linus Atorf, July 18th 2008