NAME

Robot Communication API -

Functions

void rct_init_brick_struct (rct_brick_t *brick, rct_brick_type_t type)
Initialize a brick structure. rct_status_t rct_open_brick (rct_brick_t *brick)
Open a connection to a brick. rct_status_t rct_upload_file (rct_brick_t *brick, char *filename, rct_flag_t flags)
Upload a file to the brick. rct_status_t rct_play_sound_file (rct_brick_t *brick, rct_flag_t flags, char *filename)
Instruct the brick to play a sound file. rct_status_t rct_play_tone (rct_brick_t *brick, int herz, int milliseconds)
Instruct the robo brick to play a tone. rct_status_t rct_delete_file (rct_brick_t *brick, char *filename)
rct_status_t rct_start_program (rct_brick_t *brick, char *filename)
rct_status_t rct_stop_program (rct_brick_t *brick)
rct_status_t rct_download_file (rct_brick_t *brick, char *filename)
rct_status_t rct_close_brick (rct_brick_t *brick)
rct_status_t rct_get_battery_level (rct_brick_t *brick)
rct_status_t rct_print_battery_level (rct_brick_t *brick)
rct_status_t rct_get_firmware_version (rct_brick_t *brick)
rct_status_t rct_print_firmware_version (rct_brick_t *brick)
rct_status_t rct_print_device_info (rct_brick_t *brick)
rct_status_t rct_motor_on (rct_brick_t *brick, int port, int power)
int rct_find_bricks (rct_brick_list_t *bricks, char *name, unsigned int flags)
int rct_find_nxt_bricks (rct_brick_list_t *bricks, char *name)
int rct_find_nxt_usb (rct_brick_list_t *bricks)
int rct_find_nxt_bluetooth (rct_brick_list_t *bricks, char *name)
rct_brick_t * rct_get_brick_from_list (rct_brick_list_t *list, int n)
Get brick N from an rct_brick_list_t structure. int rct_brick_count (rct_brick_list_t *bricks)
Return the number of bricks in an rct_brick_list_t structure. rct_status_t rct_set_count (rct_brick_list_t *bricks, int n)
Set the number of bricks in an rct_brick_list_t structure. rct_status_t rct_increase_count (rct_brick_list_t *bricks, int n)
Set the number of bricks in an rct_brick_list_t structur.

Detailed Description

libroboctl is a C Application Programming Interface (API) for communication with robot bricks such as Lego and VEX. It implements the basic functions of the controller communication protocols, plus higher level functions such as file uploading, downloading, etc.

The library allows programs written in C (and other languages capable of linking to C routines) to locate robo bricks on available communication links (e.g. USB, Bluetooth), open a connection to the brick, send commands and data, and retrieve data.

The top-layer C API is brick and interface independent, so you can in many cases write one program that will work with any brick over any communication interface. E.g., uploading a program file or checking the battery level is essentially the same for all bricks and it makes no difference whether we use a serial port, USB, or Bluetooth to perform these tasks.

Although use of the device independent API is encouraged for the sake of minimizing code changes for new bricks, it is not required. Some operations, are of course, specific to a certain type of brick or only make sense for certain communication links. For example, using NXT direct commands to remote-control an NXT robot connected via a USB cable could be problematic or disastrous for the robot. In these cases, a program might want a Bluetooth connection or nothing.

Example program to print some basic device info:

#include <stdio.h>
#include <sysexits.h>
#include <legoctl/legoctl.h>
/*


 *  To compile:


 *      LOCALBASE ?= /usr/local


 *


 *      cc -o print_status -I${LOCALBASE}/include print_status.c 


 *              -L${LOCALBASE}/lib -llegoctl -lusb -lbluetooth


 */


 
int     main(int argc,char *argv[])
{


    lct_brick_list_t    bricks;


    lct_brick_t         *brick;


    


    lct_find_bricks(&bricks,LCT_PROBE_DEV_NXT);


    if ( lct_brick_count(&bricks) == 0 )


    {


        fputs('Sorry, no accessible bricks found.0,stderr);


        exit(EX_UNAVAILABLE);


    }


    


    brick = lct_get_brick_from_list(&bricks,0);


    if ( lct_open_brick(brick) == LCT_OK )


    {


        lct_print_device_info(brick);


        lct_close_brick(brick);


    }


    return EX_OK;
}

Function Documentation

rct_brick_t* rct_get_brick_from_list (rct_brick_list_t * list, int n)

Get brick N from an rct_brick_list_t structure.

Parameters:

list - a structure containing an array of bricks.
n - the index of the desired brick.

Author:

Jason W. Bacon

Return a pointer to brick N in the array of bricks.

void rct_init_brick_struct (rct_brick_t * brick, rct_brick_type_t type)

Initialize a brick structure.

Parameters:

brick - Pointer to an uninitialized brick stucture.
type - RCT_NXT or RCT_RCX.

Author:

Jason W. Bacon

This function initializes the brick structure, including the brick dependent substructures for NXT, RCX, etc. This function must be called before any other functions that operate on the structure. Calling this function on a brick structure that has already been initialized and worked with may have disastrous results.

Supported bricks:

rct_status_t rct_motor_on (rct_brick_t * brick, int port, int power)

Parameters:

\param
\author

rct_status_t rct_open_brick (rct_brick_t * brick)

Open a connection to a brick.

Parameters:

brick - Pointer to an initialized brick stucture.

Author:

Jason W. Bacon

Open a connection to specified brick. The connection handle is stored within the rct_brick_t structure. The structure must be initialized with rct_init_brick() first. This is normally done by rct_find_*().

Supported bricks/interfaces:

•: NXT

•: USB
•: Bluetooth

rct_status_t rct_play_sound_file (rct_brick_t * brick, rct_flag_t flags, char * filename)

Instruct the brick to play a sound file.

Parameters:

brick - Pointer to a brick structure with an open connection.
flags - Bit flags to control play mode.
filename - Name of sound file (must be on brick already).

Author:

Jason W. Bacon

Play the specified sound file on the brick. The filename must end in '.rso', and must have been previously uploaded to the brick. The brick must first be opened with rct_open_brick().

Valid flags:

RCT_NO_FLAGS
RCT_LOOP - Play file repeatedly until manually stopped by a stop command or the NXT stop button.

Supported bricks:

•: NXT

rct_status_t rct_play_tone (rct_brick_t * brick, int herz, int milliseconds)

Instruct the robo brick to play a tone.

Parameters:

brick - Pointer to a brick structure with an open connection.
herz - Frequency of the tone (200 - 14000Hz).
milliseconds - Duration of the tone.

Author:

Jason W. Bacon

Play the specified tone for the specified duration. The brick must first be opened with rct_open_brick().

Supported bricks:

•: NXT

rct_status_t rct_upload_file (rct_brick_t * brick, char * filename, rct_flag_t flags)

Upload a file to the brick.

Parameters:

brick - Pointer to a brick structure with an open connection.
filename - name of the file on the local computer.
flags - upload mode

Author:

Jason W. Bacon

Upload the specified file (e.g. an executable or sound file) to the brick. The brick must first be opened with rct_open_brick().

Valid flags:

RCT_NO_FLAGS
RCT_OVERWRITE - replace the file if it already exists on the brick. Otherwise, upload file will fail and and return an error code.

Author

Generated automatically by Doxygen for roboctl from the source code.