The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
LEGO-NXT-1.41
River stage zero No dependents
/ LEGO::NXT

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.

IMPORTANT CONSTANTS

All of the following constants are exported in to your namespace by default, except for the OPCODES.

RET and NORET

For each request of the NXT, you must specify whether you want the NXT to send a return value.

 $NXT_RET
 $NXT_NORET

Use $NXT_RET only when you really need a return value as it does have some overhead because it has do do a second request to retrieve response data from NXT and then parses that data.

IO PORT

  $NXT_SENSOR1
  $NXT_SENSOR2
  $NXT_SENSOR3
  $NXT_SENSOR4
  
  $NXT_MOTOR_A
  $NXT_MOTOR_B
  $NXT_MOTOR_C
  $NXT_MOTOR_ALL

MOTOR CONTROL CONSTANTS

Output mode:

  $NXT_MOTOR_ON
  $NXT_BRAKE
  $NXT_REGULATED

Output regulation modes:

  $NXT_REGULATION_MODE_IDLE
  $NXT_REGULATION_MODE_MOTOR_SPEED
  $NXT_REGULATION_MODE_MOTOR_SYNC

Output run states:

  $NXT_MOTOR_RUN_STATE_IDLE
  $NXT_MOTOR_RUN_STATE_RAMPUP
  $NXT_MOTOR_RUN_STATE_RUNNING
  $NXT_MOTOR_RUN_STATE_RAMPDOWN

SENSOR TYPE

  $NXT_NO_SENSOR
  $NXT_SWITCH
  $NXT_TEMPERATURE
  $NXT_REFLECTION
  $NXT_ANGLE
  $NXT_LIGHT_ACTIVE
  $NXT_LIGHT_INACTIVE
  $NXT_SOUND_DB
  $NXT_SOUND_DBA
  $NXT_CUSTOM
  $NXT_LOW_SPEED
  $NXT_LOW_SPEED_9V
  $NXT_NO_OF_SENSOR_TYPES

SENSOR MODE

  $NXT_RAW_MODE
  $NXT_BOOLEAN_MODE
  $NXT_TRANSITION_CNT_MODE
  
  $NXT_PERIOD_COUNTER_MODE
  $NXT_PCT_FULL_SCALE_MODE
  
  $NXT_CELSIUS_MODE
  $NXT_FAHRENHEIT_MODE
  
  $NXT_ANGLE_STEPS_MODE
  $NXT_SLOPE_MASK
  $NXT_MODE_MASK

OPCODES

These are declared for internal use are not exported.

  $NXT_START_PROGRAM
  $NXT_STOP_PROGRAM
  $NXT_PLAY_SOUND_FILE
  $NXT_PLAY_TONE
  $NXT_SET_OUTPUT_STATE
  $NXT_SET_INPUT_MODE
  $NXT_GET_OUTPUT_STATE
  $NXT_GET_INPUT_VALUES
  $NXT_RESET_SCALED_INPUT_VALUE
  $NXT_MESSAGE_WRITE
  $NXT_RESET_MOTOR_POSITION
  $NXT_GET_BATTERY_LEVEL
  $NXT_STOP_SOUND_PLAYBACK
  $NXT_KEEP_ALIVE
  $NXT_LSGET_STATUS
  $NXT_LSWRITE
  $NXT_LSREAD
  $NXT_GET_CURRENT_PROGRAM_NAME
  $NXT_MESSAGE_READ

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

Returns the distance reading from the NXT

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

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

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