nxt.imt Reference Guide
Version: July 25th 2009
Return to main page
See also: Reference Guide and User Guide.
Contents:
|
|
Legend for expected/returned arguments:
|
n |
number |
|
w |
word |
|
l |
list |
|
v |
any value |
|
wl |
word or list |
|
ni |
number or number interval [from to] |
|
- |
does not return value |
|
Basics
nxt.imt allows Imagine users to control the NXT
robots from their own projects. To use nxt.imt,
run the nxtnet.exe program, which is a daemon
that communicates with one NXT brick (if you want to
connect to more than one NXT brick from the same computer,
it is possible, but then you need to start nxtnet.exe
for each brick, and use different network ports for
each brick, see nxtnet.exe -help. You need to
start nxtnet.exe each time when you want to
communicate with NXT from Imagine, but it can be started
at any time (before or after Imagine is started).
Then issue the command:
load "nxt.imt
directly from Imagine logo (or from Imagine logo project).
Feel free to modify and add other procedures according to
your needs.
The following functions and procedures are available:
Connecting and running programs
nxt_connect
:port
—> -
Connects to NXT using the specified virtual serial port (i.e. COM11).
The procedure will create an object named nxtPortOut in the MainWindow. This object is a
usual Imagine's Net object that communicates with NXT with the help of the program nxtnet.exe,
which must be running already.
All other procedures described here depend on this program running.
and on that it has already been connected using the nxt_connect procedure,
which therefore must be called first. If the nxtnet.exe program is not running,
an error message will be printed. If NXT cannot be connected, the
object is created anyway and the procedure returns normally, but the connection is not established.
You can test, if the connection
has been established using nxt_getbatterylevel described below.
Note: Since nxt_connect and the whole nxt.imt
library currently depends on the nxtPortOut object, only 1 NXT can be connected simulateneously in this version.
However, you can connect to multiple NXTs by creating multiple Net objects and running multiple nxtnet.exe
programs, each on a different port...
Example:
nxt_connect "com11
nxt_disconnect
—> -
Disconnects from NXT (closes the BlueTooth connection) and erases the associated Net object.
NXT can be connected again using the nxt_connect procedure.
Example:
nxt_disconnect
nxt_getbatterylevel
—> n
Returns the current battery voltage in milliVolts.
Example:
nxt_getbatterylevel — 8101
nxt_keepalive
—> l
Sends a 'keep alive' packet to NXT preventing it to turn off due to the inactivity.
Note: be careful when running a keep alive process in the background: it may interfere
if other processes are communicating with NXT simultaneously - you would need to use
semaphores to synchronize access to NXT. The operation returns a list [status remaining_time_ms].
Example:
nxt_keepalive — [0 117440512]
nxt_firmwareversion
—> l
Returns a list in the following format:
[status [protocol_major protocol_minor] [firmware_major firmware_minor]]
Where status is 0 if command completed successfully, or nxt error code. The remaining four
fields are numbers.
Example:
print nxt_firmwareversion —> [0 [1 124] [1 5]]
nxt_startprogram
:nxt_filename
—> -
Starts the specified program at NXT. The program must have been downloaded to NXT flash before.
Example:
nxt_startprogram "hello.rxe
nxt_stopprogram
—> -
Stops the program that is currently executed at NXT.
Example:
nxt_stopprogram
nxt_getcurrentprogramname
—> w
Returns the name of the currently executing program on NXT.
If there is no program running, the operation returns an empty word.
Example:
if empty? nxt_getcurrentprogramname [print [No program running]]
Sound control
nxt_playtone
:frequency :duration
—> -
Plays a tone of a specified frequency and duration. The command terminates immediately, so if you are sending a
sequence of tones, you need to explicitely wait in between of the tones, for example using the Imagine's wait procedure.
Example:
map [[note][nxt_playtone first :note last :note wait 50 + last :note]]
[[262 300][294 300][330 600][349 600][349 300][349 300][349 300][330 300][294 600][330 600][330 300][330 300]
[330 300][294 300][262 600][294 600][294 300][294 300][294 300][330 300][294 600][262 600][262 300][262 300]]
nxt_playsoundfile
:loop? :nxt_filename
—> -
Play the specified sound file that is stored in NXT flash. Specify "true in the first argument, if you want to play the sound in a forever loop (until another sound is played).
Example:
nxt_playsoundfile "false "Woops.rso
Note: you need to have the Woops.rso file in the NXT flash. During the NXT Logo setup, it may have been deleted. To copy it back,
open command prompt, go to NXT Logo directory, and enter the following command:
c:\nxt_logo>nxtcp nxt_flash_backup\Woops.rso com11:
(where you also need to replace com11 for the correct outgoing virtual serial port)
nxt_stopsoundplayback
—> -
Stop playing the sound file.
Example:
nxt_stopsoundplayback
Motor control
nxt_motor
:port :command :power
—> -
Control motor(s) on port 0, 1, or 2 (representing A,B,C) or combination
of motors 3 (AB), 4 (AC), 5 (BC), or 6 (ABC). The :command argument is one of:
onfwd start moving this way
onrev start moving that way
off brake the motor (active breaking, should be followed by float)
float turn the motor off (idle)
The :power argument specifies the power applied to the motor in the interval -100 to 100 (it is ingored for off
and float).
This is a convenience procedure implemented based on setoutputstate described below.
Example:
nxt_motor 5 "onfwd 60
nxt_resetmotorposition
:port :relative?
—> -
Reset motor position. Specify the motor port 0,1 or 2. Specify whether to reset position relative to last movement ("true),
or absolute position ("false), i.e. if you specify "true, block_tacho_count field will be reset to 0, otherwise the rotation_count field will be reset to 0.
Example:
nxt_resetmotorposition 0 "false
nxt_getoutputstate
:port
—> l
Get the state of the motor on port 0, 1 or 2.
Returns list [status port power mode regulation turnratio runstate tacho_limit tacho_count block_tacho_count rotation_count].
See nxt_setoutputstate below for detailed description of the fields.
Example:
nxt_getoutputstate 0 — [0 0 50 1 0 0 32 0 4721 4721 4721]
nxt_setoutputstate
:m :power :mode :reg :ratio :state :tacho
—> -
This is a universal complex command for motor control. You may wish to define your own procedures for simple motor operations
that are based on this command, or use the nxt_motor described above. The allowed values for the arguments are as follows:
:m |
0, 1, or 2 |
:power |
-100..100 |
:mode |
1=ON, 3=BRAKE, 5=REGULATED |
:reg |
0=NONE, 1=SPEED, 2=SYNCHRONIZE |
:ratio |
-100..100 |
:state |
0=IDLE, 16:RAMP-UP, 32:RUNNING, 64:RAMP-DOWN |
:tacho |
number (tacho limit), 0=run forever |
The argument :reg can be used if :mode is 5.
When the speed is regulated (:reg = 1), the actual
power is controlled by the NXT so that the speed is kept constant
even when the load changes.
Use :reg=2 to synchronize both wheels according to
the specified turning :ratio.
Example:
nxt_setoutputstate 0 50 1 0 0 32 0 (turn on motor A speed 50 and run forever)
nxt_setoutputstate 1 70 1 0 0 16 2000 (ramp-up motor B to speed 70 and stop after 2000 rotations)
nxt_setoutputstate 1 70 1 0 0 32 0 (keep motor B on speed 70 and run forever)
nxt_setoutputstate 1 0 1 0 0 64 500 (ramp-down motor B to speed 0 in 500 rotations)
nxt_setoutputstate 2 60 5 1 0 32 1000 nxt_setoutputstate 1 60 5 1 0 32 1000
(move robot that has motors on ports B and C forward rotating the motors by 1000 degrees)
nxt_setoutputstate 2 60 5 1 0 32 1000 nxt_setoutputstate 1 30 5 1 0 32 500 (turn the robot
with motors on ports B and C forward left rotating the inner wheel by 500 degrees and the outer wheel by 1000 degrees)
Sensor control
nxt_setinputmode
:port :type :mode
—> -
Setup sensor type and mode. :port is the sensor number 0, 1, 2 or 3,
:type specifies the sensor type:
1 |
switch |
2 |
temperature |
3 |
reflection |
4 |
angle |
5 |
active light sensor |
6 |
inactive light sensor |
7 |
sound in dB |
8 |
sound in dBA |
9 |
custom |
10 |
I2C (lowspeed) sensor - i.e. ultrasonic sensor |
11 |
I2C (lowspeed) sensor with 9V power on |
12 |
other |
and :mode specifies how the sensor data are interpreted:
0 |
raw |
32 |
boolean |
64 |
transition count |
96 |
periods count |
128 |
% (0-100) of full scale |
160 |
Celsius |
192 |
Fahrenheit |
224 |
Angle steps |
add: 1-31 |
slope |
Example:
nxt_setinputmode 0 1 32 (setup touch sensor on port 1)
nxt_setinputmode 1 1 32 (setup touch sensor on port 2)
nxt_setinputmode 0 1 64 (setup touch sensor on port 1, count presses and releases)
nxt_setinputmode 1 3 128 (setup RCX active light sensor on port 2, report values 0-100)
nxt_setinputmode 1 7 128 (setup NXT sound sensor on port 2, report dB values 0-100)
nxt_setinputmode 2 6 128 (setup NXT light sensor in passive mode on port 3, report values 0-100)
nxt_setinputmode 2 5 128 (setup NXT light sensor in active mode on port 3, report values 0-100)
nxt_setinputmode 3 10 0 (setup NXT ultrasonic distance sensor on port 4, the values should be read using nxt_readus).
nxt_resetinputscaledvalue
:port
—> -
Reset scaled value on sensor port.
Example:
nxt_resetinputscaledvalue 0
nxt_getinputvalues
:port
—> l
This is a general function to read from usual (non low-speed) sensors (for lowspeed sensors, i.e. ultrasonic distance
sensors, see below). :port specifies the sensor port 0,1,2, or 3. The operation returns a list
[status port valid? calibrated? sensor_type sensor_mode raw_value normalized_raw scaled calibrated]
Example:
nxt_getinputvalues 0
nxt_lswrite
:port :txlen :rxlen :data
—> -
Write to I2C bus on the specified port, the size of data to read with the next call to nxt_lsread must be specified.
Example:
nxt_lswrite 0 2 1 word char 2 char 66
nxt_lsgetstatus
:port
—> l
Get status of I2C bus on specified port. The operation returns [status bytes_ready].
Example:
nxt_lsgetstatus 0 — [224 0]
nxt_lsread
:port
—> l
Read from the I2C bus of specified input port. The operation returns list [status bytesread data1 ... dataN].
Example:
nxt_lsread 0
nxt_readus
:port
—> n
Read value from the ultrasonic sensor. This operation sends a request to the ultrasonic sensor on the specified port,
waits for the ultrasonic echo to be returned and then retrieves and returns the distance value.
Example:
nxt_readus 0
BlueTooth Messaging
nxt_messagewrite
:inbox :msg
—> -
Store BlueTooth message to the specified inbox of the connected NXT. NXT Logo uses mailbox numbers 0-9,
which correspond to mailbox numbers 1-10 of NXT-G. This procedure sends NXT-G text message. NXT-G numeric
messages are encoded as 4-byte LSB binary messages. See example below.
Example:
nxt_messagewrite 1 "hello
nxt_messagewrite 0 (word char 123 char 0 char 0 char 0) ; send numeric message 123
nxt_messageread
:remote_inbox :local_inbox :remove?
—> wl
Retrieves BlueTooth message from :remote_inbox to :local_inbox and optionally removes it
from :remote_inbox. The operation returns the retrieved message as a word, or empty list when no message
is available at the connected NXT slave.
Example:
nxt_messageread 2 2 "true
NXT file system
nxt_openread
:filename
—> l
Opens file in NXT flash for reading. The operation returns a list [status handle filesize].
Example:
let "rv nxt_openread "data.txt
if 0 = first :rv [let "h item 2 :rv]
nxt_openwrite
:filename :size
—> l
Opens file in NXT flash for writing. When opening the file, the final file size (number of bytes) must be specified.
The executable files must be written in one continuous block and thus open for writing with the nxt_openwritelinear described below.
The operation returns a list [status handle].
Example:
nxt_openwrite "data.txt 32
nxt_openwritelinear
:filename :size
—> l
Open one-block file in NXT flash for writing. Executable files must be opened using this call. The operation returns a list [status handle].
Example:
nxt_openwritelinear "prog.rxe 1231
nxt_openwritedata
:filename :size
—> l
Opens datalog file in NXT flash for writing. This file can be closed before it is completely written and then opened for appending and filled with more data. However, the final size should be specified already when it is opened for the first time.
The operation returns a list [status handle].
Example:
nxt_openwritedata "data.rdt 100
nxt_openappenddata
:filename :size
—> l
Opens file in NXT flash that was previously being written to and closed before fully written.
It is not possible to append to files that were already fully written (i.e. to their specified file size). Only datalog files can be appended (normal files are not created when closed before enough bytes have been written).
The operation returns a list [status handle size].
Example:
nxt_openappenddata "data.txt 32
nxt_read
:handle :ntoread
—> l
Reads :ntoread bytes from an open file specified by :handle.
The operation returns list [status nbytesread data1 data2 ... dataN].
Example:
print nxt_read :h 10
nxt_write
:handle :data :reply
—> l
Writes :data to an open file specified by :handle.
The operation returns a list [status nbyteswritten]. Reply should either be 0 if the write packet
should be confirmed, or 128 if the packet should not be confirmed. Confirming a packet causes
the writing of multiple packets to be very slow since the BlueTooth radio must switch the
direction of communication. It is therefore preferrable to write without confirmations: and
if there was an error during write, the following close operation will then most likely fail anyway.
Due to the limitation implied by the maximum size of the USB packets, the maximum length
of data that can be written with one call to nxt_write is (64 - 2 - 3) = 59 bytes.
Example:
nxt_write :h "hello 128
nxt_close
:handle
—> n
Closes an open file specified by :handle. The operation returns a status.
Example:
nxt_close
nxt_delete
:filename
—> n
Deletes file in the NXT flash specified by :filename. The operation returns a status.
Example:
nxt_delete "data.txt
nxt_findfirst
:filename
—> l
Searches for a specified file. You can use three types of wildcards:
*.ext, name.*, and *.*. The operation returns a list
[status handle filesize filename]. If the operation succeeds,
the handle needs to be closed after it is not used anymore.
Example:
show nxt_findfirst *.*
nxt_findnext
:handle
—> l
Searches for the next file (handle must be returned from findfirst or findnext). If file not found,
the search handle is automatically closed. The operation returns a list [status handle filesize filename]
Example:
nxt_findnext :h
nxt_ls
—> -
This procedure prints the list of files stored in the NXT flash. It is implemented using nxt_findfirst
and nxt_findnext.
Example:
nxt_ls
nxt_downloadprogram
:path :filename
—> -
Downloads a program from a specified binary NXT executable file with extension .rxe to NXT flash.
The extension must be specified. The procedure prints status information to the text screen.
Example:
nxt_downloadprogram "|C:\nxtprogs\| "prog.rxe
nxt_download
:path :filename
—> -
Downloads a file from a specified file to NXT flash. Use this for downloading non-executable files.
For executables, use nxt_downloadprogram instead. The extension must be specified.
Example:
nxt_download "|C:\measurements\| "data.txt
Miscellaneous
nxt_status2text
:status
—> l
This is a helping operation that does not communicate with NXT. It simply converts the return status
that is returned by most of the nxt_* operations to a human-readable error text message.
Example:
nxt_status2text :status
nxt_getdeviceinfo
—> l
Get the status information about the NXT brick. The operation returns a list
[status nxtname BTaddress BTsignalstrength freeflashmem]
Example:
show nxt_getdeviceinfo
nxt_deleteflash
—> -
This procedure deletes the user flash. It can take up to 3 seconds to complete.
Example:
nxt_deleteflash
ERROR CODES - returned by some of the functions
SUCCESS = 0x00 = 0
NOMOREHANDLES = 0x81 = 129
NOSPACE = 0x82 = 130
NOMOREFILES = 0x83 = 131
EOFEXSPECTED = 0x84 = 132
ENDOFFILE = 0x85 = 133
NOTLINEARFILE = 0x86 = 134
FILENOTFOUND = 0x87 = 135
HANDLEALREADYCLOSED = 0x88 = 136
NOLINEARSPACE = 0x89 = 137
UNDEFINEDERROR = 0x8A = 138
FILEISBUSY = 0x8B = 139
NOWRITEBUFFERS = 0x8C = 140
APPENDNOTPOSSIBLE = 0x8D = 141
FILEISFULL = 0x8E = 142
FILEEXISTS = 0x8F = 143
MODULENOTFOUND = 0x90 = 144
OUTOFBOUNDERY = 0x91 = 145
ILLEGALFILENAME = 0x92 = 146
ILLEGALHANDLE = 0x93 = 147
BTBUSY = 0x94 = 148
BTCONNECTFAIL = 0x95 = 149
BTTIMEOUT = 0x96 = 150
FILETX_TIMEOUT = 0x97 = 151
FILETX_DSTEXISTS = 0x98 = 152
FILETX_SRCMISSING = 0x99 = 153
FILETX_STREAMERROR = 0x9A = 154
FILETX_CLOSEERROR = 0x9B = 155