Up  

Module Mindstorm


module Mindstorm: sig .. end
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).
Version: 0.5.1
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.
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.
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.
val connect_usb : ?check_status:bool -> string -> usb conn
Not yet implemented.
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.

System commands



Files


type in_channel
Handle for reading from the brick.
val open_in : 'a conn -> string -> 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 : in_channel -> int
in_channel_length ch returns the length of the channel ch.
val close_in : in_channel -> unit
close_in ch closes the channel ch. Closing an already closed channel does nothing.
val input : in_channel -> string -> 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 out_channel
Handle for writing data to the brick.
type out_flag = [ `Append | `Data of int | `File of int | `Linear of int ]
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). 


val open_out : 'a conn -> out_flag -> string -> 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 : out_channel -> unit
close_out ch closes the channel ch. Closing an already closed channel does nothing.
val output : 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.
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
val boot : usb conn -> unit

Polling


val poll_length : 'a conn -> [ `High_speed_buffer | `Poll_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 ->
       [ `High_speed_buffer | `Poll_buffer ] -> int -> int * string
Reads bytes from the low-speed or high-speed buffer.