Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

LEGO::NXT
LEGO NXT Direct Commands API.

LEGO::NXT - LEGO NXT Direct Commands API.


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 the LEGO::NXT::Manual manpage.


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 the LEGO::NXT::Manual::Plugins manpage 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( 'xx:xx:xx:xx:xx:xx', 1 );

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.


PRIVATE METHODS

_do_cmd

_bt_connect

_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 the LEGO::NXT::Manual::Plugins manpage.


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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy