cylon-bbduino

A cylon driver and adapter to comuunicate with a bluetooth connected arduino (tested with a hc-06 module and a Arduino Uno)

This library uses node-serialport to initiate communication throught bluetooth. The HC-06 module shall be paired with the host computer prior to run the program.

It also uses a packet parser (lib/parser.js) based on spheron implementation of the orbix protocol

How to use it

Install it with NPM

% npm install cylon-bbduino --save

Test it

1. Load the bluetoothTest program (example/arduino/BluetoothTest.ino) in your arduino and open the serial monitor in the arduino IDE
2. Connect to the bluetooth device (in my case a HC-05) from your computer
3. Modify the device path to match to yours

Then, try the example/bbduino-example.js file to test the core bluetooth communication.

4. Execute :

% node example/bbduino-example.js

Or, try the example/cylon-example.js file to test a cylon implementation.

4. Execute :

% node example/cylon-example.js

Both examples should send a 'ping' command to your bbduino and print out the received packet on the serial monitor, then send a response to the client:

Arduino started bluetooth communication
FF FC 0 1 0 1 FD (7)

Communication Protocol description

Packet Structure

The packet structure is the Orbotix Sphero one (I only reduced the packet length to a single byte)

Client Command Packets

Packets are sent from Client → Bbduino in the following byte format:

SOP1    SOP2    DID    CID    SEQ    LEN    <data>    CHK

A brief description of the fields:

• SOP1: Start of Packet #1 (Always FFh) $ SOP2: Start of Packet #2 (Always FEh)
• DID: Device ID (The virtual device this packet is intended for, in practical, always 00h)
• CID: Command ID (The command code)
• SEQ: Sequence Number (This client field is echoed in the response for all synchronous commands and ignored by Bbduino, goes from 01h to FFh)
• LEN: Data Length (The number of bytes following through the end of the packet, including the checksum)
• : Data (Optional data to accompany the Command)
• CHK: Checksum (The modulo 256 sum of all the bytes from the DID through the end of the data payload, bit inverted, 1's complement)

Bbduino Command Packets

Packets are sent from Bbduino → Client in the following byte format:

SOP1    SOP2    MRSP    SEQ    LEN    <data>    CHK

A brief description of the fields:

• SOP1: Start of Packet #1 (Always FFh) $ SOP2: Start of Packet #2 (Always FEh)
• MRSP: Message Response (This is generated by the message decoder of the bbduino)
• SEQ: Sequence Number (Echoed to the client when this is a direct message response, goes from 01h to FFh)
• LEN: Data Length (The number of bytes following through the end of the packet, including the checksum)
• : Data (Optional data to accompany the Command)
• CHK: Checksum (The modulo 256 sum of all the bytes from the MRSP through the end of the data payload, bit inverted, 1's complement)

Device ID 00h - CORE API

Ping - 01h

The Ping command is used to verify both a solid data link with the Client and that Bbduino is awake and dispatching commands.

• Command

DID    CID    SEQ    LEN    CHK
00h    01h    <any>  01h    <computed>

• Response

MRSP    SEQ       LEN    CHK
01h     <echoed>  01h    <computed>

GetVersion - 02h

The Ping command is used to verify both a solid data link with the Client and that Bbduino is awake and dispatching commands.

• Command

DID    CID    SEQ    LEN    CHK
00h    02h    <any>  01h    <computed>

• Response

MRSP    SEQ       LEN    VERSIONS    CHK
02h     <echoed>  07h    <versions>  <computed>

The Get Version command returns software and hardware information. The data record structure is comprised of fields for each resource that encodes the version number according to the specified format.

MDL      0  Model number of the Bbduino
HW       1  Hardware version code
MA-ver   2  Main Application version byte
MA-rev   3  Main Application revision byte
API-maj  4  API major revision code this firmware implements
API-min  5  API minor revision code this firmware implements

Device ID 01h - COMMAND API

Set Bbduino Speed - 30h

• Command

DID    CID    SEQ    LEN    DATA    CHK
01h    30h    <any>  05h    <data>  <computed>

The first byte of data is the directon of the left motor (forward is coded with 01h, backward is coded with 03h), the second byte is the speed of the left motor (00h to 255h, 0 means the motor is stopped) The third and fourth bytes of data concern the right motor.

LDIR    0  Left motor direction (01h: forward, 03h: backward)
LSPEED  1  Left motor speed (from 00h to FFh)
RDIR    2  Right motor direction (01h: forward, 03h: backward)
RSPEED  3  Right motor speed (from 00h to FFh)

• Response

MRSP    SEQ       LEN    CHK
30h     <echoed>  01h    <computed>

Set Bbduino Servomotor position - 31h

• Command

DID    CID    SEQ    LEN    DATA    CHK
01h    31h    <any>  02h    <data>  <computed>

Position goes from 0 (left positio) to 255 (right position) Center position is 128.

POS    0  Servo Position

• Response

MRSP    SEQ       LEN    CHK
31h     <echoed>  01h    <computed>

Mac Os X

Snow Leopard 10.7.5

Open Bluetooth prerences, select HC-O5 and configure serial port. Create a outgoing port (/dev/cu.HC-05-DevB)

Dependencies

• node-serialport

Todo

[ ] Implement auto-reconnect [ ] Add promises to API [ ] Implement Power charge getter, and notificatons [ ] Implement ultrasnic sensor motor command [ ] Implement ultrasnic sensor detection getter and notification [ ] Implement heading calibration [ ] Implement buzzer command [ ] Implemet data streaming (accelerometer, battery voltage, heading, ultrasonic detection, ...) [ ] Implement LED blink command