mindstorm 0.5.4 · OCaml Package

OCaml-mindstorm is a library that enables you to drive Lego mindsotrm NXT bricks from OCaml (the computer is the master and the brick is the slave). Communication with the NXT brick is done through bluetooth (and possibly eventually USB).

author Christophe Troestler <Christophe.Troestler\@umons.ac.be>

type usb

type bluetooth

type 'a conn

Abstract type representing a connection to a LEGO� mindstorm brick. The type parameter indicates whether this connection is a USB or a bluetooth one.

val connect_bluetooth : ?check_status:bool -> string -> bluetooth conn

connect_bluetooth bdaddr connects through bluetooth to the brick with bluetooth address bdaddr.

parameter check_status
set the default value for the check_status optional argument. This global default allows to easily globally activate status checking for a given connection. Checking the status ensures the command was transmitted properly but incur a cost of 60ms between two transmissions. Default: false.

raises Unix.Unix_error
in case of a connection problem. In particular, Unix.Unix_error(Unix.EHOSTDOWN, _,_) is raised if the brick is not turned on.

module USB : sig ... end

Functions to choose and connect to NXT bricks connected through USB. So far, it works on Linux (users of other platforms, your help is welcome).

val close : 'a conn -> unit

close conn closes the connection conn to the brick.

Exception for errors

type error =

| No_more_handles
(*
All 16 handles are in use.
*)
| No_space
| No_more_files
| EOF_expected
| Not_a_linear_file
| No_linear_space
| Undefined_error
| File_is_busy
| No_write_buffers
| Append_not_possible
| File_is_full
| File_exists
| Module_not_found
| Out_of_boundary
| Illegal_file_name
| Pending
(*
Pending communication transaction in progress
*)
| Empty_mailbox
(*
Specified mailbox queue is empty
*)
| Failed
(*
Request failed (i.e. specified file not found)
*)
| Unknown
(*
Unknown command opcode
*)
| Insane
(*
Insane packet
*)
| Out_of_range
(*
Data contains out-of-range values
*)
| Bus_error
(*
Communication bus error, can indicate a device failure.
*)
| Buffer_full
(*
No free memory in communication buffer
*)
| Invalid_conn
(*
Specified channel/connection is not valid
*)
| Busy_conn
(*
Specified channel/connection not configured or busy
*)
| No_program
(*
No active program
*)
| Bad_size
(*
Illegal size specified
*)
| Bad_mailbox
(*
Illegal mailbox queue ID specified
*)
| Bad_field
(*
Attempted to access invalid field of a structure
*)
| Bad_io
(*
Bad input or output specified
*)
| Out_of_memory
(*
Insufficient memory available
*)
| Bad_arg
(*
Bad arguments
*)

Error codes

exception Error of error

This exception can be raised by any of the functions below except when the optional argument ~check_status is set to false. Note that checking for errors leads to up to approximately a 60ms latency between two commands.

exception File_not_found

Raised to indicate that a file is not present on the brick.

Direct commands

module Program : sig ... end

Starting and stopping programs (.rxe files) on the brick.

module Motor : sig ... end

Output ports.

module Sensor : sig ... end

Input ports.

module Sound : sig ... end

Play sounds (.rso files) and tones.

module Message : sig ... end

Read and write messages from the 10 message queues. This can be thought as advanced direct commands.

System commands

Files

type 'a in_channel

Handle for reading from the brick.

val open_in : 'a conn -> string -> 'a in_channel

open_in conn fname opens the file named fname on the brick for reading. The channel must be closed with Mindstorm.close_in. Close it as soon as possible as channels are a scarce resource.

raises Invalid_argument
if fname is not a ASCIIZ string with maximum 15.3 characters.

val in_channel_length : 'a in_channel -> int

in_channel_length ch returns the length of the channel ch.

val close_in : 'a in_channel -> unit

close_in ch closes the channel ch. Closing an already closed channel does nothing.

val input : 'a in_channel -> Bytes.t -> int -> int -> int

input ch buf ofs len reads a block of data of length len from the channel ch and write it to buf starting at position ofs.

raises End_of_file
if there is no more data to read.

type 'a out_channel

Handle for writing data to the brick.

type out_flag = [

| `File of int
| `Linear of int
| `Data of int
| `Append

]

The standard NXT firmware requires that executable files and icons are linear but all other types of files (including sound files) can be non-contiguous (i.e., fragmented).

`File length: Default file, the parameter is its length.
`Linear length: Write a linear file, the parameter is its length.

val open_out : 'a conn -> out_flag -> string -> 'a out_channel

open_out conn flag fname opens the file fname for writing. The channel must be closed with Mindstorm.close_in. Close it as soon as possible as channels are a scarce resource.

If the the file exists, Error File_exists is raised. If the brick does not like the extension you use, Error File_is_full may be raised.

val close_out : 'a out_channel -> unit

close_out ch closes the channel ch. Closing an already closed channel does nothing.

val output : 'a out_channel -> string -> int -> int -> int

output ch buf ofs len ouputs the substring buf.[ofs .. ofs+len-1] to the channel fd. Returns the number of bytes actually written. If you try to write more bytes than declared when opening the file, Error File_is_full is raised.

val remove : 'a conn -> string -> unit

remove conn fname remove the file fname from the brick.

module Find : sig ... end

List files on the brick matching a given pattern.

Brick information

val firmware_version : 'a conn -> int * int * int * int

firmware_version conn returns a tuple (p1, p0, f1, f0) where p1 is the major version of the protocol, p0 is the minor version of the protocol, f1 is the major version of the firmware, f0 is the minor version of the firmware,

val set_brick_name : ?check_status:bool -> 'a conn -> string -> unit

set_brick_name conn name change the name to which one is connected through conn to name.

parameter check_status
whether to check the status returned by the brick (and raise Error accordingly). Default: see Mindstorm.connect_bluetooth.

type brick_info = {

brick_name : string;
(*
NXT name (set with Mindstorm.set_brick_name)
*)
bluetooth_addr : string;
(*
Bluetooth address
*)
signal_strength : int;
(*
Bluetooth signal strength (for some reason is always 0)
*)
free_user_flash : int;
(*
Free user FLASH
*)

}

val get_device_info : 'a conn -> brick_info

get_device_info conn returns some informations about the brick connected through conn.

val keep_alive : 'a conn -> int

keep_alive conn returns the current sleep time limit in milliseconds.

val battery_level : 'a conn -> int

battery_level conn return the voltages in millivolts of the battery on the brick.

val delete_user_flash : 'a conn -> unit

val bluetooth_reset : usb conn -> unit

bluetooth_reset conn performs a factory reset of the brick. (The type system does will a allow this command to be transmitted via bluetooth because all bluetooth functionality is reset by this command.)

val boot : usb conn -> unit

Polling

val poll_length : 'a conn -> [ `Poll_buffer | `High_speed_buffer ] -> int

Returns the number of bytes for a command in the low-speed buffer or the high-speed buffer (0 = no command is ready).

val poll_command : 
  'a conn ->
  [ `Poll_buffer | `High_speed_buffer ] ->
  int ->
  int * string