Robotics.NXT

This module defines an interface over Bluetooth to a NXT brick as defined in Lego Mindstorms NXT Bluetooth Developer Kit, Appendix 1 - Communication protocol and Appendix 2 - Direct commands. It also defines some additional functions not available directly otherwise.

Initialization

withNXT :: FilePath -> NXT a -> IO a

Function which initializes and terminates Bluetooth connection to the NXT brick (using initialize and terminate) and in-between runs given computation. It terminates Bluetooth connection on an exception, too, rethrowing it afterwards.

defaultDevice :: FilePath

Default Bluetooth serial device filename for current operating system. Currently always /dev/rfcomm0.

Motors

setOutputState :: OutputPort -> OutputPower -> [OutputMode] -> RegulationMode -> TurnRatio -> RunState -> TachoLimit -> NXT ()

Sets output port (motor) state. This is the main function for controlling a motor.

setOutputStateConfirm :: OutputPort -> OutputPower -> [OutputMode] -> RegulationMode -> TurnRatio -> RunState -> TachoLimit -> NXT ()

Same as setOutputState but also request a confirmation. Useful to assure the command was really accepted. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

getOutputState :: OutputPort -> NXT OutputState

Gets output port (motor) current state. In additional to values used with setOutputState also TachoCount, BlockTachoCount and RotationCount values are available which tell you current position of a motor.

resetMotorPosition :: OutputPort -> MotorReset -> NXT ()

Resets one of three position counters for a given output port.

Sensors

setInputMode :: InputPort -> SensorType -> SensorMode -> NXT ()

Sets input port (sensor) type and mode.

setInputModeConfirm :: InputPort -> SensorType -> SensorMode -> NXT ()

Same as setInputMode but also request a confirmation. Useful to assure the command was really accepted. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

getInputValues :: InputPort -> NXT InputValue

Gets input port (sensor) values. This is the main function for reading a sensor.

resetInputScaledValue :: InputPort -> NXT ()

Resets input port (sensor) scaled value.

Miscellaneous

getVersion :: NXT Version

Gets firmware and protocol versions of the NXT brick.

getDeviceInfo :: NXT DeviceInfo

Gets device (the NXT brick) information: name, Bluetooth 48 bit address in the string format, strength of Bluetooth signal (not implemented in current NXT firmware versions, use bluetoothRSSI or bluetoothLinkQuality as an alternative), free space on flash.

getBatteryLevel :: NXT Voltage

Gets current battery level (in volts).

isBatteryRechargeable :: NXT Bool

Is battery used in the NXT brick rechargeable?

keepAlive :: NXT ()

Sends a keep alive (turned on) packet. It prevents the NXT brick from automatically powering off. Other commands do not prevent that from hapenning so it is useful to send this packet from time to time if you want to prevent powering off.

keepAliveConfirm :: NXT ()

Same as keepAlive but also request a confirmation. Useful to assure the command was really accepted. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

getSleepTimeout :: NXT Duration

Gets current sleep timeout setting (in seconds) after which the NXT brick automatically powers off if not prevented with a keep alive packet (use keepAlive to send one). This setting is cached.

getLastKeepAliveTime :: NXT (Maybe POSIXTime)

When was a last keep alive packet send?

stopEverything :: NXT ()

Helper function which stops all NXT brick activities: stops motors and disables sensors.

shutdown :: NXT ()

Shutdowns (powers off) the NXT brick. You have to manually turn it on again.

Remote Programs

It is possible to remotely run and control (with messages) programs on the NXT brick. Those here are low-level functions but check also high-level Robotics.NXT.Remote and Robotics.NXT.MotorControl modules.

startProgram :: FileName -> NXT ()

Starts a given program on the NXT brick.

startProgramConfirm :: FileName -> NXT ()

Same as startProgram but also request a confirmation. Useful to assure the command was really accepted, but this does not assure that the program has really started successfully (especially not that it is already running when the confirmation is received). Use ensureStartProgram for that. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

stopProgram :: NXT ()

Stops a currently running program.

stopProgramConfirm :: NXT ()

Same as stopProgram but also request a confirmation. Useful to assure the command was really accepted. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

stopProgramExisting :: NXT ()

Same as stopProgramConfirm but it also requires that the program was really running. It throws a NXTException otherwise.

ensureStartProgram :: FileName -> NXT ()

Helper function which first ensures that no other program is running and then ensures that a given program is really running before it returns.

getCurrentProgramName :: NXT (Maybe String)

Gets the name of the currently running program, if any.

Messages

It is possible to control programs on the NXT brick with messages. Those here are low-level functions but check also high-level Robotics.NXT.Remote and Robotics.NXT.MotorControl modules.

messageWrite :: Inbox -> String -> NXT ()

Writes a message to the given inbox queue of the running remote program. A message length is limited to 58 characters/bytes. A queue is limited to 5 messages.

messageWriteConfirm :: Inbox -> String -> NXT ()

Same as messageWrite but also request a confirmation. Useful to assure the command was really accepted. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

messageRead :: RemoteInbox -> RemoveMessage -> NXT String

Reads a message from the currently running program from a given remote inbox queue. A queue is limited to 5 messages. It throws a NXTException if there is no message in a remote inbox queue.

maybeMessageRead :: RemoteInbox -> RemoveMessage -> NXT (Maybe String)

Same as messageWrite but returns Nothing if there is no message in a given remote inbox queue.

ensureMessageRead :: RemoteInbox -> RemoveMessage -> NXT String

Same as messageWrite but if there is no message in a given remote inbox queue it retries until there is.

Sounds

playSoundFile :: LoopPlayback -> FileName -> NXT ()

Plays a given sound file.

playSoundFileConfirm :: LoopPlayback -> FileName -> NXT ()

Same as playSoundFile but also request a confirmation. Useful to assure the command was really accepted. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

playTone :: Frequency -> Duration -> NXT ()

Plays a tone with a given frequency (in hertz) for a given duration (in seconds).

stopSoundPlayback :: NXT ()

Stops current sound file playback.

stopSoundPlaybackConfirm :: NXT ()

Same as stopSoundPlayback but also request a confirmation. Useful to assure the command was really accepted. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

Low Speed (I2C)

With those low-level functions it is possible to communicate with digital sensors attached to the NXT brick. But check also high-level Robotics.NXT.Sensor.Ultrasonic and Robotics.NXT.Sensor.Compass modules.

lowspeedGetStatus :: InputPort -> NXT Int

Gets number of bytes available to read.

lowspeedWrite :: InputPort -> RxDataLength -> TxData -> NXT ()

Writes data. At most 16 bytes can be written at a time.

Reply data length must be specified in the write command since reading from the device is done on a master-slave basis.

lowspeedWriteConfirm :: InputPort -> RxDataLength -> TxData -> NXT ()

Same as lowspeedWrite but also request a confirmation. Useful to assure the command was really accepted. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

lowspeedRead :: InputPort -> NXT RxData

Reads data. The protocol does not support variable-length return packages so the response always contains 16 data bytes with invalid data padded with zeros.

Filesystem

openWrite :: FileName -> FileSize -> NXT FileHandle

Opens a given file for writing as a linked list of flash sectors.

openWriteLinear :: FileName -> FileSize -> NXT FileHandle

Opens a given file for writing as a linear contiguous block of flash memory (required for user programs and certain data files).

write :: FileHandle -> FileData -> NXT ()

Writes data to a file. At most 61 bytes can be written at a time.

writeConfirm :: FileHandle -> FileData -> NXT ()

Same as write but also request a confirmation. Useful to assure the command was really accepted. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

close :: FileHandle -> NXT ()

Closes a file.

closeConfirm :: FileHandle -> NXT ()

Same as close but also request a confirmation. Useful to assure the command was really accepted. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

delete :: FileName -> NXT ()

Deletes a given file.

deleteConfirm :: FileName -> NXT ()

Same as delete but also request a confirmation. Useful to assure the command was really accepted. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

deleteExisting :: FileName -> NXT ()

Same as deleteConfirm but it also requires that the file exists before deletion. It throws a NXTException otherwise.

IO Map

Interface to NXT firmware is based on internal IO map interface. All commands are in fact just pretty wrappers to this interface, but it is possible to use it directly and thus gain some additional possibilities which are not available otherwise (some of those are already wrapped in this interface's additional functions and feel free to suggest more if you need them).

getModuleID :: ModuleName -> NXT (Maybe ModuleID)

Helper function to get an ID of a module matching a given module name. Each module encompass some firmware functionality. Function caches IDs so it hopefully retrieves it from a cache of previous requests.

listModules :: ModuleName -> NXT [ModuleInfo]

Helper function to get information about all modules matching a given module name (which can be a wild card).

requestFirstModule :: ModuleName -> NXT (ModuleHandle, Maybe ModuleInfo)

Requests information about the first module matching a given module name (which can be a wild card). Returned module handle can be used for followup requests and has to be closed when not needed anymore.

requestNextModule :: ModuleHandle -> NXT (ModuleHandle, Maybe ModuleInfo)

Requests information about the next module matching previously requested module name (which can be a wild card). Returned module handle can be used for followup requests and has to be closed when not needed anymore.

closeModuleHandle :: ModuleHandle -> NXT ()

Closes module handle of previously requested module information.

closeModuleHandleConfirm :: ModuleHandle -> NXT ()

Same as closeModuleHandle but also request a confirmation. Useful to assure the command was really accepted. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

readIOMap :: ModuleID -> IOMapOffset -> IOMapLength -> NXT IOMapData

Reads data from an IO map of a given module. At most 119 bytes can be read at a time.

You probably have to know what different values at different positions mean and control. The best way is to check NXT firmware source code.

writeIOMap :: ModuleID -> IOMapOffset -> IOMapData -> NXT ()

Writes data to an IO map of a given module. At most 54 bytes can be written at a time.

You probably have to know what different values at different positions mean and control. The best way is to check NXT firmware source code.

writeIOMapConfirm :: ModuleID -> IOMapOffset -> IOMapData -> NXT ()

Same as writeIOMap but also request a confirmation. Useful to assure the command was really accepted. In a case of an error it throws a NXTException.

Confirmation requires a change of the direction of NXT Bluetooth communication which takes around 30 ms.

Internals

Be careful when using those functions as you have to assure your program is well-behaved: you should see NXTInternals as a token you have to pass around in order, not reusing or copying values. (The only exception is that you can reuse the token initally returned by initialize in terminate call, even if you have used it in-between.) They are exposed so that you can decouple initalization, execution and termination phase. If you do not need that use withNXT.

initialize :: FilePath -> IO NXTInternals

Opens and intializes a Bluetooth serial device communication.

terminate :: NXTInternals -> IO ()

Stops all NXT activities (by calling stopEverything) and closes the Bluetooth serial device communication. NXTInternals token must not be used after that anymore.

runNXT :: NXT a -> NXTInternals -> IO (a, NXTInternals)

Runs a computation in a context of a given NXTInternals token, returning a value and a new token.

execNXT :: NXT a -> NXTInternals -> IO NXTInternals

Runs a computation in a context of a given NXTInternals token, returning just a new token.

Bluetooth utils

getDeviceInfo returns zero for Bluetooth signal strength as this is not implemented in current NXT firmware versions. Here are functions which retrieve that from a host (computer) Bluetooth stack.

bluetoothRSSI :: NXT Int

Gets received signal strength indicator (RSSI) of the Bluetooth connection to the NXT brick.

Currently supported only on Linux. It throws a NXTException otherwise.

bluetoothLinkQuality :: NXT Int

Gets link quality of the Bluetooth connection to the NXT brick.

Currently supported only on Linux. It throws a NXTException otherwise.

Types

data NXT a

Monad which encompasses interface to the NXT brick.

Instances

Monad NXT

Functor NXT

MonadFix NXT

MonadIO NXT

data Version

The format of version is "major.minor". To format it use printf "%d.%02d" major minor.

Constructors

Version FirmwareVersion ProtocolVersion

Instances

Bounded Version

Eq Version

Ord Version

Read Version

Show Version

data FirmwareVersion

Constructors

FirmwareVersion Major Minor

Instances

Bounded FirmwareVersion

Eq FirmwareVersion

Ord FirmwareVersion

Read FirmwareVersion

Show FirmwareVersion

data ProtocolVersion

Constructors

ProtocolVersion Major Minor

Instances

Bounded ProtocolVersion

Eq ProtocolVersion

Ord ProtocolVersion

Read ProtocolVersion

Show ProtocolVersion

type Major = Int

type Minor = Int

data DeviceInfo

Constructors

DeviceInfo Name BTAddress BTStrength FlashFree

Instances

Eq DeviceInfo

Ord DeviceInfo

Read DeviceInfo

Show DeviceInfo

type Name = String

Name of the NXT brick.

type BTAddress = String

Bluetooth address of the NXT brick in the string format.

type BTStrength = Int64

Strength of the Bluetooth signal. Not implemented in current NXT firmware versions. Use bluetoothRSSI or bluetoothLinkQuality as an alternative.

type FlashFree = Int64

Free flash space on the NXT brick (in bytes).

data OutputState

Constructors

OutputState OutputPort OutputPower [OutputMode] RegulationMode TurnRatio RunState TachoLimit TachoCount BlockTachoCount RotationCount

Instances

Eq OutputState

Ord OutputState

Read OutputState

Show OutputState

data OutputPort

Constructors

A

Output port (motor) A.

B

Output port (motor) B.

C

Output port (motor) C.

Instances

Bounded OutputPort

Enum OutputPort

Eq OutputPort

Ord OutputPort

Read OutputPort

Show OutputPort

type OutputPower = Int

Power and direction. In [-100, 100] range.

data OutputMode

Constructors

MotorOn

Enables PWM power according to speed.

Brake

Voltage is not allowed to float between PWM pulses, improves accuracy, uses more power.

Regulated

Required in conjunction with output regulation mode setting.

Instances

Bounded OutputMode

Enum OutputMode

Eq OutputMode

Ord OutputMode

Read OutputMode

Show OutputMode

data RegulationMode

Constructors

RegulationModeIdle

Disables regulation.

RegulationModeMotorSpeed

Auto adjust PWM duty cycle if motor is affected by physical load. Really works only if there is room for that (not that motor is already running at the maximum power).

RegulationModeMotorSync

Attempts to keep rotation in sync with another motor that has this set. Also involves turn ratio.

Instances

Bounded RegulationMode

Enum RegulationMode

Eq RegulationMode

Ord RegulationMode

Read RegulationMode

Show RegulationMode

type TurnRatio = Int

In regulated synced mode the difference between two motors. In [-100, 100] range.

data RunState

Constructors

MotorRunStateIdle

Disables power to motor.

MotorRunStateRampUp

Ramping to a new speed set-point that is greater than the current speed set-point.

MotorRunStateRunning

Enables power to motor.

MotorRunStateRampDown

Ramping to a new speed set-point that is less than the current speed set-point.

MotorRunStateHold

Hold at the current position.

Instances

Bounded RunState

Enum RunState

Eq RunState

Ord RunState

Read RunState

Show RunState

type TachoLimit = Int64

Target tacho limit for a motor movement. 0 means no limit. It is an unsigned value (you select direction of motor movement with sign of OutputPower value).

type TachoCount = Int64

Internal (absolute) tacho counter. Number since the last reset of the motor tacho counter.

type BlockTachoCount = Int64

Block-relative position counter. Current position relative to the last programmed movement.

type RotationCount = Int64

Program-relative position counter. Current position relative to the last reset of the rotation sensor for this motor.

data MotorReset

Constructors

AbsolutePosition

Resets program-relative position counter (RotationCount).

RelativePosition

Resets block-relative position counter (BlockTachoCount)

InternalPosition

Resets internal movement counters (also TachoCount), cancels current goal and resets internal error-correction system.

Instances

Bounded MotorReset

Enum MotorReset

Eq MotorReset

Ord MotorReset

Read MotorReset

Show MotorReset

data InputPort

Constructors

One

Input port (sensor) 1.

Two

Input port (sensor) 2.

Three

Input port (sensor) 3.

Four

Input port (sensor) 4.

Instances

Bounded InputPort

Enum InputPort

Eq InputPort

Ord InputPort

Read InputPort

Show InputPort

data InputValue

Constructors

InputValue InputPort Valid Calibrated SensorType SensorMode RawADValue NormalizedADValue ScaledValue CalibratedValue

Instances

Bounded InputValue

Eq InputValue

Ord InputValue

Read InputValue

Show InputValue

type Valid = Bool

True if new data value should be seen as valid data.

type Calibrated = Bool

True if calibration file found and used for CalibratedValue.

data SensorType

Type of the sensor currently attached to InputPort. NoSensor turns off the sensor.

Constructors

NoSensor

Switch

Temperature

Reflection

Angle

LightActive

LightInactive

SoundDB

SoundDBA

Custom

Lowspeed

Lowspeed9V

NoOfSensorTypes

Instances

Bounded SensorType

Enum SensorType

Eq SensorType

Ord SensorType

Read SensorType

Show SensorType

data SensorMode

Constructors

RawMode

Reports scaled value equal to the raw value.

BooleanMode

Reports scaled value as 1 true or 0 false, false if raw value > 55% of total range, true if < 45%.

TransitionCntMode

Reports scaled value as number of transitions between true and false.

PeriodCounterMode

Reports scaled value as number of transitions from false to true, then back to false.

PctFullScaleMode

Reports scaled value as % of full scale reading for a configured sensor type.

CelsiusMode

For reporting temperature in celsius.

FahrenheitMode

For reporting temperature in fahrenheit.

AngleStepsMode

Reports scaled value as count of ticks on RCX-style rotation sensor.

Instances

Bounded SensorMode

Enum SensorMode

Eq SensorMode

Ord SensorMode

Read SensorMode

Show SensorMode

type RawADValue = Int

Raw A/D value. Device dependent.

type NormalizedADValue = Int

Normalized A/D value. Type dependent. In [0, 1023] range.

type ScaledValue = Int

Scaled value. Mode dependent. In percent.

type CalibratedValue = Int

Value scaled according to calibration. Unused in current NXT firmware versions.

type Voltage = Ratio Int

Voltage value (in volts).

type Duration = NominalDiffTime

Time duration (in seconds).

data Inbox

Inbox on the NXT brick into which the host (computer) queues messages for the program running there.

Constructors

Inbox0

Inbox1

Inbox2

Inbox3

Inbox4

Inbox5

Inbox6

Inbox7

Inbox8

Inbox9

Instances

Bounded Inbox

Enum Inbox

Eq Inbox

Ord Inbox

Read Inbox

Show Inbox

data RemoteInbox

Outbox on the NXT brick where the program running there queues messages for the host (computer). There is a convention that only RemoteInbox10 - RemoteInbox19 outboxes are used for this purpose so that lower ones can be used for inter-brick communication. But this convention is not really obeyed in practice.

Constructors

RemoteInbox0

RemoteInbox1

RemoteInbox2

RemoteInbox3

RemoteInbox4

RemoteInbox5

RemoteInbox6

RemoteInbox7

RemoteInbox8

RemoteInbox9

RemoteInbox10

RemoteInbox11

RemoteInbox12

RemoteInbox13

RemoteInbox14

RemoteInbox15

RemoteInbox16

RemoteInbox17

RemoteInbox18

RemoteInbox19

Instances

Bounded RemoteInbox

Enum RemoteInbox

Eq RemoteInbox

Ord RemoteInbox

Read RemoteInbox

Show RemoteInbox

type RemoveMessage = Bool

Should the message be remove from the queue once received?

type LoopPlayback = Bool

Loop playback of the sound file?

type Frequency = Int

Frequency of the played tone (in hertz).

type RxDataLength = Int

At most 16 data bytes can be read at a time.

type TxData = [Word8]

type RxData = [Word8]

type DeviceAddress = Word8

Address of the device (sensor) on the I2C bus.

type Command = Word8

I2C device command.

type Measurement = Int

I2C device measurement value.

type FileName = String

Filename of the file on the NXT brick filesystem. In 15.3 format.

type FileSize = Int

Size of the file on the NXT brick filesystem.

type FileHandle = Int

Handle of the opened file on the NXT brick filesystem.

type FileData = [Word8]

data ModuleInfo

Type of the IO map module information.

Constructors

ModuleInfo ModuleName ModuleID ModuleSize ModuleIOMapSize

Instances

Eq ModuleInfo

Ord ModuleInfo

Read ModuleInfo

Show ModuleInfo

type ModuleName = String

Module name extension is .mod. For some functions this can be also a wild card.

type ModuleID = Int64

type ModuleSize = Int64

type ModuleIOMapSize = Int

type ModuleHandle = Int

Handle for traversing of modules. Only one module handle can be opened at a time so be careful to close them when not needed anymore.

type IOMapOffset = Int

type IOMapLength = Int

type IOMapData = [Word8]

data TimeoutException

Timeout exception for NXT IO operations.

Constructors

TimoutException

Instances

Show TimeoutException

Typeable TimeoutException

Exception TimeoutException

data NXTInternals

A token used for exposed internal functions.

Instances

Show NXTInternals

Typeable NXTInternals

Errors

Possible error codes and their descriptions are described in Lego Mindstorms NXT Bluetooth Developer Kit, Appendix 1 - Communication protocol and Appendix 2 - Direct commands.

data NXTException

Exception for NXT interface errors. Currently only one exception is defined which takes textual description as an argument.

Constructors

NXTException String

Instances

Show NXTException

Typeable NXTException

Exception NXTException