Michael Collins > LEGO-NXT > LEGO::NXT

Download:
LEGO-NXT-2.00-1.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 2.00   Source  

NAME ^

LEGO::NXT - LEGO NXT Direct Commands API.

SYNOPSIS ^

  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,
  );

DESCRIPTION ^

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.

MANUAL ^

There is a manual for this module with an introduction, tutorials, plugins, FAQ, etc. See LEGO::NXT::Manual.

SUPPORT ^

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/

PLUGINS ^

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.

METHODS ^

new

  $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.

initialize_ultrasound_port

  $nxt->initialize_ultrasound_port($NXT_SENSOR_4);

Sets the port of your choosing to use the ultrasound digital sensor.

get_ultrasound_measurement_units

  $nxt->get_ultrasound_measurement_units($NXT_SENSOR_4);

Returns the units of measurement the US sensor is using (cm? in?)

get_ultrasound_measurement_byte

  $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.

get_ultrasound_continuous_measurement_interval

  $nxt->get_ultrasound_measurement_interval($NXT_SENSOR_4);

Returns the time period between ultrasound measurements.

get_ultrasound_read_command_state

  $nxt->get_ultrasound_read_command_state($NXT_SENSOR_4);

Returns whether the sensor is in one-off mode or continuous measurement mode (the default).

get_ultrasound_actual_zero

  $nxt->get_ultrasound_actual_zero($NXT_SENSOR_4);

Returns the calibrated zero-distance value for the sensor

get_ultrasound_actual_scale_factor

  $nxt->get_ultrasound_actual_scale_factor($NXT_SENSOR_4);

Returns the scale factor used to compute distances

get_ultrasound_actual_scale_divisor

  $nxt->get_ultrasound_actual_scale_divisor($NXT_SENSOR_4);

Returns the scale divisor used to compute distances

set_ultrasound_off

  $nxt->set_ultrasound_off($NXT_SENSOR_4);

Turns the ultrasound sensor off

set_ultrasound_single_shot

  $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

set_ultrasound_continuous_measurement

  $nxt->set_ultrasound_continuous_measurement($NXT_SENSOR_4);

Puts the sensor in continuous measurement mode.

set_ultrasound_event_capture_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.

ultrasound_request_warm_reset

  $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. =)

set_ultrasound_continuous_measurement_interval

  $nxt->set_ultrasound_continuous_measurement_interval($NXT_SENSOR_4);

Sets the sampling interval for the range sensor.

TODO: Document valid values...

set_ultrasound_actual_zero

  $nxt->set_ultrasound_actual_zero($NXT_SENSOR_4);

Sets the calibrated zero value for the sensor.

set_ultrasound_actual_scale_factor

  $nxt->set_ultrasound_actual_scale_factor($NXT_SENSOR_4);

Sets the scale factor used in computing range.

set_ultrasound_actual_scale_divisor

  $nxt->set_ultrasound_actual_scale_divisor($NXT_SENSOR_4);

Sets the scale divisor used in computing range.

start_program

  $nxt->start_program($NXT_NORET,$filename)

Start a program on the NXT called $filename

stop_program

  $nxt->stop_program($NXT_NORET)

Stop the currently executing program on the NXT

play_tone

  $nxt->play_tone($NXT_NORET,$pitch,$duration)

Play a Tone in $pitch HZ for $duration miliseconds

play_sound_file

  $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.

set_output_state

  $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.

set_input_mode

  $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.

get_output_state

  $ret = $nxt->get_output_state($NXT_RET,$port)

Retrieve the current ouput state of $port.

  $ret  A hashref containing the port attributes.

get_input_values

  $ret = $nxt->get_input_values($NXT_RET,$port)

Retrieve the current sensor input values of $port.

  $ret  A hashref containing the sensor value attributes.

reset_input_scaled_value

  $nxt->reset_input_scaled_value($NXT_NORET,$port)

If your sensor port is using scaled values, reset them.

message_write

  $nxt->message_write($NXT_NORET,$mailbox,$message)

Write a $message to local mailbox# $mailbox.

reset_motor_position

  $nxt->reset_motor_position($NXT_NORET,$port,$relative)

TODO: Specifics

get_battery_level

  $ret = $nxt->get_battery_level($NXT_RET)

  $ret  A hash containing battery attributes - voltage in MV

set_stop_sound_playback

  $nxt->set_stop_sound_playback($NXT_NORET)

Stops the currently playing sound file

keep_alive

  $nxt->keep_alive($NXT_NORET)

Prevents the NXT from entering sleep mode

ls_get_status

  $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

ls_write

  $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

ls_read

  $nxt->ls_read($NXT_RET,$port)

Read a pending I2C message from a digital I2C device.

ls_request_response

  $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.

get_current_program_name

  $ret = $nxt->get_current_program_name($NXT_RET)

$ret is a hash containing info on the current;y running program.

message_read

  $ret = $nxt->message_read($NXT_RET,$remotebox,$localbox,$remove)

Read a message.

NXT SYSTEM COMMANDS ^

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.

sys_open_read

  $ret = $nxt->sys_open_read($filename);

Opens a system file for reading, returns a file descriptor.

sys_open_write

  $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.

sys_read

  $ret = $nxt->sys_read($fd,$nbytes);

Reads $nbytes from open file descriptor $fd. I believe $nbytes should be < 60 when using USB.

sys_write

  $ret = $nxt->sys_write($fd,$data);

Writes $data to open file descriptor $fd.

sys_close

  $ret = $nxt->sys_close($fd);

Closes the file descriptor $fd.

sys_delete

  $ret = $nxt->sys_delete($filename);

Deletes a file on the NXT with name $filename.

sys_find_first

  $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.

sys_find_next

  $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

sys_get_firmware_version

  $ret = $nxt->sys_get_firmware_version();

Does what it says.

sys_open_write_linear

  $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.

sys_open_read_linear

  $ret = $nxt->sys_open_read_linear($filename);

Opens a system file for reading, returns the memory address of the file (NOT FD).

sys_open_write_data

  $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.

sys_open_append_data

  $ret = $nxt->sys_open_append_data($filename);

Opens a system file for appendinf (data mode?), returns the fd and available size.

sys_boot

  $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!

sys_set_brick_name

  $ret = $nxt->sys_set_brick_name($filename);

Does what it says. I believe this defaults to NXT and is used in Bluetooth identification.

sys_get_device_info

  $ret = $nxt->sys_get_device_info();

Returns various informations about the NXT including Bluetooth info and available flash.

sys_poll_command_length

  $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.

sys_poll_command

  $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.

sys_bluetooth_factory_reset

  $ret = $nxt->sys_bluetooth_factory_reset($filename);

Resets the on-board bluetooth chip to factory defaults.

PRIVATE METHODS ^

_do_cmd

_parse_get_output_state

_parse_get_input_values

_parse_get_battery_level

_parse_ls_get_status

_parse_ls_read

_parse_get_current_program_name

_parse_message_read

_parse_generic_ret

import

This is a custom import method for supporting plugins. See LEGO::NXT::Manual::Plugins.

AUTHOR ^

Michael Collins <michaelcollins@ivorycity.com>

CONTRIBUTORS ^

Aran Deltac <bluefeet@cpan.org>

LICENSE ^

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

COPYRIGHT ^

The LEGO::NXT module is Copyright (c) 2006 Michael Collins. USA. All rights reserved.

SUPPORT / WARRANTY ^

See Additional Resources at http://nxt.ivorycity.com

LEGO::NXT is free open source software. IT COMES WITHOUT WARRANTY OF ANY KIND.

syntax highlighting: