This page presents the API for managing sensors/actuators of the NXT. The documentation is largely inspired from http://lejos-osek.sourceforge.net/ecrobot_c_api.htm. This documentation focuses on the basic NXT sensors/actuators (motors, light sensor, touch sensor, sound sensor, ultrasonic sensor, bluetooth, USB, LCD display). For a more comprehensive documentation see http://lejos-osek.sourceforge.net/ecrobot_c_api.htm.
ECRobot API consists of low level device API and ECRobot wrapper API (prefix of the API is ecrobot_) that is designed for real-time control application programming. Gray colored wrapper API in the below tables has duplicated feature of the original low level device API, so it is better to use the original API to reduce the run time overhead. When you use ECRobot API, you need to include ecrobot_interface.h in your source code.
In the following documentation, green-colored comments give shortcomings of the Trampoline port, or mention Trampoline-specific features.
Shortcuts:
- Servo Motor API
- Light Sensor API
- Touch Sensor API
- Sound Sensor API
- Ultrasonic Sensor API
- Bluetooth API
- USB API
- LCD display API
- Sound API
- NXT internal API
Servo Motor API
|
Description
|
int nxt_motor_get_count(U32 n) |
gets Servo Motor revolution count in degree.Count may be negative or positive. Counts are not reset to zero when reaching 360 (resp. -360).
Parameters: |
void nxt_motor_set_count(U32 n, int count) |
sets Servo Motor revolution count in degree.
Parameters: |
void nxt_motor_set_speed(U32 n, int speed_percent, int brake) |
sets Servo Motor PWM value and brake mode.
Parameters: |
S32 ecrobot_get_motor_rev(U8 port_id) |
gets Servo Motor revolution value in degree. Wrapper of nxt_motor_get_count.
Parameters: |
void ecrobot_set_motor_speed(U8 port_id, S8 speed) |
sets Servo Motor PWM value. Wrapper of nxt_motor_set_speed, but brake mode is fixed as brake.
Parameters: |
void ecrobot_set_motor_mode_speed(U8 port_id, S32 mode, S8 speed) |
sets Servo Motor brake mode and PWM value. Wrapper of nxt_motor_set_speed
Parameters: |
Remark: does not work on Trampoline
Light Sensor API
|
Description
|
void ecrobot_set_light_sensor_active(U8 port_id) |
turns on infra-red light of Light Sensor. This function should be implemented in the device initialize hook routine.
Parameters: |
void ecrobot_set_light_sensor_inactive(U8 port_id) |
turns off infra-red light of Light Sensor. This function should be implemented in the device terminate hook routine.
Parameters: |
U16 ecrobot_get_light_sensor(U8 port_id) |
gets Light Sensor raw A/D data. Greater value means darker (or lower reflection).
Parameters: |
Touch Sensor API
|
Description
|
U8 ecrobot_get_touch_sensor(U8 port_id) |
gets Touch Sensor status.Parameters: port_id: NXT_PORT_S1, NXT_PORT_S2, NXT_PORT_S3, NXT_PORT_S4 Returns: 0 (not touched), 1 (touched) |
Sound Sensor API
|
Description
|
U16 ecrobot_get_sound_sensor(U8 port_id) |
gets Sound Sensor raw A/D data. Smaller value means louder sound.
Parameters: |
Ultrasonic Sensor has its brain to communicate with the ARM7 via another I2C communication channel. ecrobot_get_sonar_sensor sends a protocol data to communicate with the Ultrasonic Sensor. However, actual data transaction between the ARM7 and the Ultrasonic Sensor is done by an ISR triggered by this function call, so there is one execution cycle delay to achieve consistent data acquisition.
Ultrasonic Sensor API
|
Description
|
void ecrobot_init_sonar_sensor(U8 port_id) |
initializes a port for I2C communication for Ultrasonic Sensor. This function should be implemented in the device initialize hook routine.
Parameters: |
S32 ecrobot_get_sonar_sensor(U8 port_id) |
gets Ultrasonic Sensor measurement data in cm via I2C.
Parameters: |
void ecrobot_term_sonar_sensor(U8 port_id) |
terminates I2C communication used for Ultrasonic Sensor. This function should be implemented in the device terminate hook routine.
Parameters: |
Inside of the NXT, there is a Bluecore chip to handle Bluetooth communication. The ARM7 uses UART to communicate with the Bluecore chip. In LEGO MINDSTORMS NXT Bluetooth Developer Kit, standard LEGO firmware supports a lot of communication protocols, however, ECRobot API does not support all LEGO standard communication protocol (i.e. no direct control, no diagnosis…).
– In case of NXT-PC Bluetooth communication, A Windows application program (NXT GamePad) is available to remotely control a NXT and acquire the NXT internal data (data logging).
– In case of NXT-NXT, only one NXT to one NXT communication is supported. Device configurations for a Bluetooth connection needs to be implemented in the code.
Remark: not tested yet on Trampoline
Bluetooth API
|
Description
|
void ecrobot_init_bt_master(const U8 *bd_addr, const CHAR *pin) |
initializes NXT as the Bluetooth master device and establish a connection with a slave NXT. Bluetooth Device Address (BD_ADDR) consists of 48 bits, however, NXT requires additional 8 bits (total 7 bytes), so the last 8 bits should always be 0x00. This API needs to be implemented in a loop (e.g. ecrobot_device_initialize or a background Task).Parameters: bd_addr: Slave NXT’s Bluetooth Device Address. If a slave NXT had 00:16:53:04:F1:B3 BD_ADDR, bd_addr should be defined such as: const U8 bd_addr[7] = {0x00,0x16,0x53,0x04,0xF1,0xB3,0x00}; pin: pin code string. Maximum character length is 16. (e.g. “LEJOS-OSEK”) Returns: none |
void ecrobot_init_bt_slave(const CHAR *pin) |
initializes NXT as the Bluetooth slave device and establish a connection with a master device (PC, master NXT). This API needs to be implemented in a loop (e.g. ecrobot_device_initialize or a background Task).
Parameters: |
void ecrobot_init_bt_connection(void) |
initializes Bluetooth device and establish a connection with PC. PINCODE for the connection is pre-fixed as “MATLAB”. This API needs to be implemented in a loop (e.g. ecrobot_device_initialize or a background Task).
Parameters: |
U8 ecrobot_get_bt_device_name(CHAR* bd_name) |
get Bluetooth friendly device name.
Parameters: |
U8 ecrobot_set_bt_device_name(const CHAR* bd_name) |
sets Bluetooth friendly device name.
Note that user specified friendly device name using this function seems to be appeared in the Windows Bluetooth device dialog only when NXT BIOS is used as the firmware. Parameters: |
SINT ecrobot_get_bt_status(void) |
gets the status of Bluetooth device. To communicate with other device, Bluetooth device status has to be BT_STREAM.
Parameters: |
U32 ecrobot_send_bt_packet(U8 *buf, U32 bufLen) |
sends data packet to a Bluetooth device (PC, master/slave NXT).
Parameters: |
U32 ecrobot_read_bt_packet(U8 *buf, U32 bufLen) |
reads data packet from a Bluetooth device (PC, master/slave NXT).
Parameters: |
U8 ecrobot_set_bt_factory_settings(void) |
resets all settings in the persistent settings in the BlueCore chip. The BlueCore chip should be restarted (may need to remove the battery) after calling this function. Otherwise old values can be floating around the BlueCore chip causing unexpected behavior.
Parameters: |
void ecrobot_term_bt_connection(void) |
terminates Bluetooth connection with a device (PC, master/slave NXT).
Parameters: |
void ecrobot_bt_data_logger(S8 data1, S8 data2) |
sends pre-fixed NXT internal status data. Data packet size is 32bytes and the following NXT internal status data is sent to PC via Bluetooth. This API is designed for NXT GamePad and NXT GamePad will save all data as a CSV file.
data packet 0-3bytes: system tick in msec, data type U32 Parameters: |
Trampoline uses LEGO Fantom driver for USB host application program and USB communication protocol becomes more consistent (i.e. explict connect/disconnect) and provides more functionalities.
Remark: not tested yet on Trampoline
USB API
|
Description
|
void ecrobot_init_usb(void) |
initializes USB functionality in the NXT. This function must be invoked in ecrobot_device_initialize.
Parameters: |
SINT ecrobot_set_name_usb(U8* name) |
sets name to the NXT. By default, “nxt” is set as the device name in ecrobot_init_usb.
Parameters: |
U8 ecrobot_process1ms_usb(void) |
USB process handler to establish a connection with a host. This function must be invoked every 1msec. (i.e. in a loop with 1msec wait, OSEK/JSP 1msec peiodical Task)
Parameters: |
SINT ecrobot_read_usb(U8* buf, U32 off, U32 len) |
reads USB data from host after a USB connection was established.
Parameters: |
SINT ecrobot_send_usb(U8* buf, U32 off, U32 len) |
sends USB data to host after a USB connection was established.
Parameters: |
SINT ecrobot_disconnect_usb(void) |
disconnects a current connection with host. This API enables to implement connect/disconnect sequence in application. This function makes USB device name being default, so it needs to invoke ecrobot_set_name_usb to change the device name to be user specified device name.
Parameters: |
void ecrobot_term_usb(void) |
terminates USB functionality in the NXT.
Parameters: |
Trampoline supports for monochrome BMP files to draw graphics in the LCD display. User can design LCD graphics in BMP editor on PC and the BMP image can be displayed in the LCD on the NXT. Long lines are truncated to 16 characters.
Remark: not tested yet on Trampoline
LCD display API
|
Description
|
SINT ecrobot_bmp2lcd(const CHAR *file, U8 *lcd, S32 width, S32 height) |
converts a monochrome BMP file image to a BMP array data.
Parameters: |
void display_bitmap_copy(const U8 *data, U32 width, U32 depth, U32 x, U32 y) |
displays a BMP array data to LCD.
Parameters: |
void display_update(void) |
updates LCD display. Without a call to display_update, nothing appears on the LCD.
Parameters: |
void display_clear(U32 updateToo) |
clears LCD display buffer.
Parameters: |
void display_goto_xy(int x, int y) |
specifies text display position. Top left is (0,0).
Parameters: |
void display_string(const char *str) |
stores string into LCD display buffer.
Parameters: |
void display_hex(U32 val, U32 places) |
stores integer value into LCD display buffer to display hex expression.
Parameters: |
void display_unsigned(U32 val, U32 places) |
stores unsigned integer value into LCD display buffer.
Parameters: |
void display_int(int val, U32 places) |
stores signed integer value into LCD display buffer.
Parameters: |
void ecrobot_status_monitor(const CHAR *target_name) |
displays NXT internal status (application name, system tick, battery voltage, raw A/D data, motor revolutions, Bluetooth connection status, and Ultrasonic Sensor data) on the LCD. It is recommended to invoke this API in a low speed periodical Task (i.e. 500msec).
Parameters: |
nxtOSEK supports for 8 bit monoral PCM WAV file to play a sound. WAV file sound (e.g. music, voice…) can be directly played in the NXT. GCC provides objcopy which enables to link WAV files to a nxtOSEK binary executable. Under samples directory, there is a WAV file example (wavtest)
Remark: does not work on Trampoline
Sound API
|
Description
|
SINT ecrobot_sound_tone(U32 freq, U32 ms, U32 vol) |
plays a tone, given its frequency, duration and volume. Frequency is audible from about 31 to 2100 Hertz. The duration argument is in hundreds of a seconds (centiseconds, not milliseconds) and is truncated at 256, so the maximum duration of a tone is 2.56 seconds.
Parameters: |
SINT ecrobot_sound_wav(const CHAR *file, U32 length, S32 freq, U32 vol) |
plays a 8bit monoral PCM WAV sound file.
Parameters: |
void sound_freq(U32 freq, U32 ms) |
plays a tone, given its frequency and duration. Frequency is audible from about 31 to 2100 Hertz. The duration argument is in hundreds of a seconds (centiseconds, not milliseconds) and is truncated at 256, so the maximum duration of a tone is 2.56 seconds.
Parameters: |
NXT internal API
|
Description
|
U8 ecrobot_is_ENTER_button_pressed(void) |
returns the status of ENTER (ENTR) button.
Parameters: |
U8 ecrobot_is_RUN_button_pressed(void) |
returns the status of RUN button.
Parameters: |
U16 ecrobot_get_battery_voltage(void) |
gets battery voltage data.
Parameters: |
U32 systick_get_ms(void) |
gets system tick in msec. system tick is started when the NXT is turned on (not started when an application begins)
Parameters: |
U32 ecrobot_get_systick_ms(void) |
gets system tick in msec. Wrapper of systick_get_ms.
Parameters: |
void systick_wait_ms(U32 ms) |
waits for specified msec.
Parameters: |