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.\n",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;
}

See also

nbc(1), nxc(1), nqc(1), legoctl(1), vexctl(1), ape(1)