LEGO::NXT - LEGO NXT Direct Commands API.
use LEGO::NXT; # Create a new Bluetooth/NXT object by connecting to # a specific bluetooth address and channel. my $nxt = LEGO::NXT->new( 'xx:xx:xx:xx:xx:xx', 1 ); $nxt->play_sound_file($NXT_NORET, 0,'! Attention.rso'); $res = $nxt->get_battery_level($NXT_RET); # Turn on Motor 1 to full power. $res = $nxt->set_output_state( $NXT_RET, $NXT_SENSOR1, 100, $NXT_MOTORON|$NXT_REGULATED, $NXT_REGULATION_MODE_MOTOR_SPEED, 0, $NXT_MOTOR_RUN_STATE_RUNNING, 0, );
This module provides low-level control of a LEGO NXT brick over bluetooth using the Direct Commands API. This API will not enable you to run programs on the NXT, rather, it will connect to the NXT and issue real-time commands that turn on/off motors, retrieve sensor values, play sound, and more.
Users will leverage this API to control the NXT directly from an external box.
This is known to work on Linux. Other platforms are currently untested, though it should work on any system that has the Net::Bluetooth module.
There is a manual for this module with an introduction, tutorials, plugins, FAQ, etc. See LEGO::NXT::Manual.
If you would like to get some help join the #lego-nxt IRC chat room on the MagNET IRC network (the official perl IRC network). More information at:
http://www.irc.perl.org/
LEGO::NXT supports the ability to load plugins.
use LEGO::NXT qw( Scorpion );
Plugins provide higher level and more sophisticated means of handling your NXT. Likely you will want to use a plugin if you want to control your NXT as the methods in LEGO::NXT itself are very low level and tedious to use by themselves.
Please see LEGO::NXT::Manual::Plugins for more details about how to use plugins (and write your own!) as well as what plugins are available to you.
$nxt = LEGO::NXT->new( new LEGO::NXT:BlueComm('xx:xx:xx:xx',0) ); $nxt = LEGO::NXT->new( new LEGO::NXT:USBComm() );
Creates a new NXT object, however a connection is not established until the first direct command is issued. Argument 1 should be the bluetooth address of your NXT (from "hcitool scan" for instance). Argument 2 is the channel you wish to connect on -- 1 or 2 seems to work.
$nxt->initialize_ultrasound_port($NXT_SENSOR_4);
Sets the port of your choosing to use the ultrasound digital sensor.
$nxt->get_ultrasound_measurement_units($NXT_SENSOR_4);
Returns the units of measurement the US sensor is using (cm? in?)
$nxt->get_ultrasound_measurement_byte($NXT_SENSOR_4,$byte);
Returns the distance reading from the NXT from register $byte. $byte should be a value 0-7 indicating the measurement register in the ultrasound sensor. In continuous measurement mode, measurements are stored in register 0 only, however in one-shot mode, each time one-shot is called a value will be stored in a new register.
$nxt->get_ultrasound_measurement_interval($NXT_SENSOR_4);
Returns the time period between ultrasound measurements.
$nxt->get_ultrasound_read_command_state($NXT_SENSOR_4);
Returns whether the sensor is in one-off mode or continuous measurement mode (the default).
$nxt->get_ultrasound_actual_zero($NXT_SENSOR_4);
Returns the calibrated zero-distance value for the sensor
$nxt->get_ultrasound_actual_scale_factor($NXT_SENSOR_4);
Returns the scale factor used to compute distances
$nxt->get_ultrasound_actual_scale_divisor($NXT_SENSOR_4);
Returns the scale divisor used to compute distances
$nxt->set_ultrasound_off($NXT_SENSOR_4);
Turns the ultrasound sensor off
$nxt->set_ultrasound_single_shot($NXT_SENSOR_4);
Puts the sensor in single shot mode - it will only store a value in a register once each time this function is called
$nxt->set_ultrasound_continuous_measurement($NXT_SENSOR_4);
Puts the sensor in continuous measurement mode.
$nxt->set_ultrasound_event_capture_mode($NXT_SENSOR_4);
In this mode the US sensor will detect only other ultrasound sensors in the vicinity.
$nxt->ultrasound_request_warm_reset($NXT_SENSOR_4);
I won't lie - I don't know what a "warm reset" is, but it sounds like a nice new beginning to me. =)
$nxt->set_ultrasound_continuous_measurement_interval($NXT_SENSOR_4);
Sets the sampling interval for the range sensor.
TODO: Document valid values...
$nxt->set_ultrasound_actual_zero($NXT_SENSOR_4);
Sets the calibrated zero value for the sensor.
$nxt->set_ultrasound_actual_scale_factor($NXT_SENSOR_4);
Sets the scale factor used in computing range.
$nxt->set_ultrasound_actual_scale_divisor($NXT_SENSOR_4);
Sets the scale divisor used in computing range.
$nxt->start_program($NXT_NORET,$filename)
Start a program on the NXT called $filename
$nxt->stop_program($NXT_NORET)
Stop the currently executing program on the NXT
$nxt->play_tone($NXT_NORET,$pitch,$duration)
Play a Tone in $pitch HZ for $duration miliseconds
$nxt->play_sound_file($NXT_NORET,$repeat,$file)
Play a NXT sound file called $file. Specify $repeat=1 for infinite repeat, 0 to play only once.
$nxt->set_output_state($NXT_NORET,$port,$power,$mode,$regulation,$turnratio,$runstate,$tacholimit)
Set the output state for one of the motor ports.
$port One of the motor port constants. $power -100 to 100 power level. $mode An bitwise or of output mode constants. $regulation One of the motor regulation mode constants. $runstate One of the motor runstate constants. $tacholimit Number of rotation ticks the motor should turn before it stops.
$nxt->set_input_mode($NXT_NORET,$port,$sensor_type,$sensor_mode)
Configure the input mode of a sensor port.
$port A sensor port constant. $sensor_type A sensor type constant. $sensor_mode A sensor mode constant.
$ret = $nxt->get_output_state($NXT_RET,$port)
Retrieve the current ouput state of $port.
$ret A hashref containing the port attributes.
$ret = $nxt->get_input_values($NXT_RET,$port)
Retrieve the current sensor input values of $port.
$ret A hashref containing the sensor value attributes.
$nxt->reset_input_scaled_value($NXT_NORET,$port)
If your sensor port is using scaled values, reset them.
$nxt->message_write($NXT_NORET,$mailbox,$message)
Write a $message to local mailbox# $mailbox.
$nxt->reset_motor_position($NXT_NORET,$port,$relative)
TODO: Specifics
$ret = $nxt->get_battery_level($NXT_RET) $ret A hash containing battery attributes - voltage in MV
$nxt->set_stop_sound_playback($NXT_NORET)
Stops the currently playing sound file
$nxt->keep_alive($NXT_NORET)
Prevents the NXT from entering sleep mode
$nxt->ls_get_status($NXT_RET,$port)
Determine whether there is data ready to read from an I2C digital sensor. NOTE: The Ultrasonic Range sensor is such a sensor and must be interfaced via the ls* commands
$nxt->ls_write($NXT_RET,$port,$txlen,$rxlen,$txdata)
Send an I2C command to a digital I2C sensor.
$port The sensor port of the I2C sensor $txlen The length of $txdata $rxlen The length of the expected response (sensor/command specific) $txdata The I2C command you wish to send in packed byte format. NOTE: The NXT will suffix the command with a status byte R+0x03, but you dont need to worry about this. Do not send it as part of $txdata though - it will result in a bus error.
NOTE: The Ultrasonic Range sensor is such a sensor and must be interfaced via the ls* commands
$nxt->ls_read($NXT_RET,$port)
Read a pending I2C message from a digital I2C device.
$nxt->ls_request_response($port,$txlen,$rxlen,$txdata)
Higher level I2C request-response routine. Loops to ensure data is ready to read from the sensor and returns the result.
$ret = $nxt->get_current_program_name($NXT_RET)
$ret is a hash containing info on the current;y running program.
$ret = $nxt->message_read($NXT_RET,$remotebox,$localbox,$remove)
Read a message.
Caution. Use these only if you know what you're doing.
If you know what you're doing, these methods can be very useful. If you don't know what you're doing, you will probably end up with a dead robot. Beware. Seriously.
NOTE: Every system command requires a return value, so there's no need to pass NXT_RET.
$ret = $nxt->sys_open_read($filename);
Opens a system file for reading, returns a file descriptor.
$ret = $nxt->sys_open_write($filename,$size);
Opens (creates?) a system file for writing, returns a file descriptor. You must specify the size of the file you wish to write to.
$ret = $nxt->sys_read($fd,$nbytes);
Reads $nbytes from open file descriptor $fd. I believe $nbytes should be < 60 when using USB.
$ret = $nxt->sys_write($fd,$data);
Writes $data to open file descriptor $fd.
$ret = $nxt->sys_close($fd);
Closes the file descriptor $fd.
$ret = $nxt->sys_delete($filename);
Deletes a file on the NXT with name $filename.
$ret = $nxt->sys_find_first($search);
Finds a file on the system with filename $search. Searches may use wildcards: *.*, *.txt, etc. This command will return statstr=>"File not found" on failure. The filehandle MUST be closed when finished with the query.
$ret = $nxt->sys_find_next($fd);
Finds the next matching file on the system from sys_find_first. $fd is the descriptor returned from sys_find_first
$ret = $nxt->sys_get_firmware_version();
Does what it says.
$ret = $nxt->sys_open_write_linear($filename,$size);
Opens a system file for writing (raw data mode? update me... ), returns a file descriptor. You must specify the size of the file you wish to write to.
$ret = $nxt->sys_open_read_linear($filename);
Opens a system file for reading, returns the memory address of the file (NOT FD).
$ret = $nxt->sys_open_write_data($filename,$size);
Opens a system file for writing (data mode? update me... ), returns a file descriptor. You must specify the size of the file you wish to write to.
$ret = $nxt->sys_open_append_data($filename);
Opens a system file for appendinf (data mode?), returns the fd and available size.
$ret = $nxt->sys_boot()
Boot the NXT. DO NOT USE UNLESS YOU **REALLY** KNOW WHAT YOU'RE DOING!!! YOU CAN BREAK YOUR NXT!!! YOU HAVE BEEN WARNED.
NOTE: USB Interface ONLY!
$ret = $nxt->sys_set_brick_name($filename);
Does what it says. I believe this defaults to NXT and is used in Bluetooth identification.
$ret = $nxt->sys_get_device_info();
Returns various informations about the NXT including Bluetooth info and available flash.
$ret = $nxt->sys_poll_command_length($buffer_number);
Polls for the number of bytes ready in the command buffer. $buffer_number = 0x00 for poll buffer $buffer_number = 0xA1 for the high speed buffer * I have no idea what this does as of this writing.
$ret = $nxt->sys_poll_command($buffer_number,$command_length);
Polls the command buffer. $buffer_number = 0x00 for poll buffer $buffer_number = 0xA1 for the high speed buffer * I have no idea what this does as of this writing.
$ret = $nxt->sys_bluetooth_factory_reset($filename);
Resets the on-board bluetooth chip to factory defaults.
This is a custom import method for supporting plugins. See LEGO::NXT::Manual::Plugins.
Michael Collins <michaelcollins@ivorycity.com>
Aran Deltac <bluefeet@cpan.org>
You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.
The LEGO::NXT module is Copyright (c) 2006 Michael Collins. USA. All rights reserved.
See Additional Resources at http://nxt.ivorycity.com
LEGO::NXT is free open source software. IT COMES WITHOUT WARRANTY OF ANY KIND.
To install LEGO::NXT, copy and paste the appropriate command in to your terminal.
cpanm
cpanm LEGO::NXT
CPAN shell
perl -MCPAN -e shell install LEGO::NXT
For more information on module installation, please visit the detailed CPAN module installation guide.