BotSense IP Proxy Client-Server Protocol

Intro

The transport of all messages between the server and the server's registered clients is TCP/IP. A client establishes communication with server by making a connection request to the listening TCP port of the server (default port: 9195). If the server has client space, the connection is accepted and the communication is established.

Closing of the client's port automatically unregisters the client from the server.

See bsproxy_if.h for the message API.

The BotSense Proxy client-server messages can be partitioned in several sets. Table 1 lists these groups.

Server Client-Server Messages	Proxied Device Core Client-Server Messages
BrainPack Foot Client-Server Messages	BrainPack IMU Client-Server Messages
BrainPack Hand Client-Server Messages	BrainPack Compass Client-Server Messages
RS-232 Controller Client-Server Messages	RCB-3 Controller Client-Server Messages
Table 1: Message Sets

---

Message Structure

Clients make requests to the server. The server performs the requested actions and replies back to the client with the results.

The application messages contain a header and (optionally) a body. The header and body contain message fields. Fields are packed big-endian, with the most significant byte sent first. The maximum length (number of bytes) of messages is 256 (BSPROXY_MSG_MAX_LEN) bytes.

Basic Field Data Types

The basic data types exchanged between the clients and the server are listed in Table 2.

type	description
byte	uninterpreted 8-bit octet
char	1 byte ASCII character
u8	1 byte unsigned integer
u16	2 byte unsigned integer
u32	4 byte unsigned integer
zstr	zero-terminated ASCII string
Table 2: Field Data Types

Client Request Application Message Header

All client requests contain a 3 byte (BSPROXY_CMD_HDR_LEN) header. Table 3 describes the request header format.

field	type	description
msg_id	u8	request message id
tid	u8	client generated transaction id
blen	u8	length of request message body (number of bytes)
Table 3: Client Request Header Fields

Server Response Application Message Header

All server responses contain a 4 byte (BSPROXY_RSP_HDR_LEN) header. Table 4 describes the response header format.

field	type	description
msg_id	u8	echoed client's request message id
tid	u8	echoed client's transaction id
pf	char	client request result: passed ('P') or failed ('F')
blen	u8	length of response message body (number of bytes)
Table 4: Server Response Header Fields

---

Server Error Response

If a client message is corrupted, contain bad values, or the request cannot be serviced, a fail repsonse message is sent.

field	type	description
msg_id	u8	echoed client's request message id
tid	u8	echoed client's transaction id
'F'	char	request failed
blen	u8	strlen(error_msg)+1
error_msg	zstr	error message with trailing 0
Table 5: Server Fail Response Message

The exception to the above fail response is when the recieved request is completely undecipherable by bsproxy. In this case msg_id = BSPROXY_MSGID_ERROR, and tid = 0. Otherwise, the format is identical.

---

Server Client-Server Messages

The BotSense Proxy server directed messages provide: and the bsproxy daemon. Server-directed functions return information about the the server and provide server configuration options.

Loopback - Loopback client request. The request's message body is looped back without any interpretation. msg_id: BSPROXY_MSGID_LOOPBACK

client request body

msg_body byte blen any data byte(s)

server pass response body

msg_body byte blen any data byte(s)

Server Log - Set bsproxy's diagnostics logging level. Logging messages are written to the log file on the target server. Default output stream is stderr. msg_id: BSPROXY_MSGID_LOG

client request body

level u8 1 loggging level 0-6

server pass response body

level u8 1 adjusted logging level

Server Version - Get bsproxy's version string. msg_id: BSPROXY_MSGID_VERSION

client request body

no body

server pass response body

version zstr 1 Version string. There are 4 subfields separated by whitespace. server - server name x.y.z - dotted version yyyy.mm.dd - compiled date hh.mm.ss - compiled time

Proxied Device Info - Get list of server supported proxied device types. See proxied_devices for list of device types. msg_id: BSPROXY_MSGID_PROXY_INFO

client request body

no body

server pass response body

prox_dev_vec u8 blen enumeration of supported proxied device types

---

Proxied Device Core Client-Server Messages

The BotSense Proxy proxied device core messages provide standard operator semantics on target devices. Proxied device standard operators are open, close, read, write, transaction, ioctl, and scan.

The I²C proxied device operator semantics provide raw access to target I²C Bus. Since the BrainPack I²C devices are attached to a target I²C Bus, clients with opened BrainPack proxied devices may also take advantage of the raw I/O operations.

The RS-232 proxied device operator semantics provide raw access to the target point-to-point serial connection. Since the RCB-3 Controller is an RS-232 device (over USB), clients with opened RCB-3 proxied devices may also take advantage of the raw I/O operations.

Open Proxied Device - Open a bsproxy supported proxied device. Client access to a proxied device is through the opened proxied device handle returned in the response message. The client must keep track of its opened device handles. msg_id: BSPROXY_MSGID_DEV_OPEN

client request body

dev_type u8 1 proxied device type (see proxied_devices ) i2c_addr1 u8 1 BrainPack I2C address. Note 1: field is only present for BrainPack devices. dev_name zstr 1 target device name (e.g /dev/i2c/0)

server pass response body

handle u8 1 proxied device handle

Close Proxied Device - Close a bsproxy proxied device. The close operation frees up the resource for the client. The client may then reuse resource for a new proxied device. The server actually only closes a proxied device when the device's reference count is zero. That is, when no other opened proxied devices from all clients reference the underlining system resource. msg_id: BSPROXY_MSGID_DEV_CLOSE

client request body

handle u8 1 opened proxied device handle

server pass response body

handle u8 1 closed proxied device handle

Proxied Device Read - Read data from a proxied device. The bytes read are uninterpreted and simply passed back to the client. msg_id: BSPROXY_MSGID_DEV_READ

client request body

handle u8 1 opened proxied device handle i2c_addr1 u8 1 I2C address Note 1: field is only present for BSPROXY_DEVTYPE_I2C devices. rlen u8 1 number of bytes to read

server pass response body

rdata byte blen bytes read

Proxied Device Write - Write data to a proxied device. The bytes written are uninterpreted. msg_id: BSPROXY_MSGID_DEV_WRITE

client request body

handle u8 1 opened proxied device handle i2c_addr1 u8 1 I2C address Note 1: field is only present for BSPROXY_DEVTYPE_I2C devices. wdata byte blen-x bytes to write where x is either 1 or 2.

server pass response body

wlen u8 1 number of bytes written

Proxied Device Transaction - Perform a transaction with a proxied device. A transaction is a write/read operation. All device bytes are uninterpreted. msg_id: BSPROXY_MSGID_DEV_TRANS

client request body

handle u8 1 opened proxied device handle i2c_addr1 u8 1 I2C address Note 1: field is only present for BSPROXY_DEVTYPE_I2C devices. rlen u8 1 number of bytes to read wdata byte blen-x bytes to write where x is either 2 or 3.

server pass response body

rdata byte blen bytes read

Proxied Device IOCTL - Issue a device control call to a proxied device. msg_id: BSPROXY_MSGID_DEV_IOCTL

RS-232 client request body

handle u8 1 opened proxied device handle baudrate u16 1 baud rate: 9600, 115200, etc bytesize u8 1 byte size: 5 - 8 bits parity char 1 parity: 'N', 'E', 'O' stopbits u8 1 stop bits: 1, 2 xonxoff u8 1 software flow control: 0=disable, 1=enable rtscts u8 1 hardware flow control: 0=disable, 1=enable

other client request body

N/A or not implemented

server pass response body

no body

Proxied Device Scan - Scan for attach resources on the proxied device. msg_id: BSPROXY_MSGID_DEV_SCAN

client request body

handle u8 1 opened proxied device handle

I2C server pass response body

num_scanned u8 1 number of discovered devices i2c_addr_vec u8 num_scanned vector of discovered device addresses

Proxied Device Command - Execute a proxied device specific command. See the following BrainPack and RCB-3 message sections for the specific, higher-level proxied devices messages. msg_id: BSPROXY_MSGID_DEV_CMD

client request body

handle u8 1 opened proxied device handle dev_cmd_id u8 1 proxied device specific command id dev_cmd_body byte blen-2 proxied device specific command body (if any)

server pass response body

dev_rsp_body byte blen proxied device specific response body (if any)

---

BrainPack Foot Client-Server Messages

The BrainPack Foot proxied device is an attached I²C Bus device with an application specific message set. All specific communication with the foot is through the Proxied Device Command.

Get Foot IDs - Get the BrainPack device identifiers. dev_cmd_id: BSPROXY_BPFOOT_CMDID_GET_IDS

client device command body

no body

server pass response body

dev_id u16 1 BrainPack device id version u8 1 firmware version

Calibrate Foot - Calibrate BrainPack Foot sensors. Currently, the calibration sets the zero mark at the current pressure readings. To calibarate: lift the robot up so that the feet are unloaded, issue this calibrate command, and the sensors are calibrated. Note: calibration could change. dev_cmd_id: BSPROXY_BPFOOT_CMDID_CAL

client device command body

no body

server pass response body

no body

Get Raw Foot Data - Get the BrainPack Foot raw sensor readings. There are 8 (BSPROXY_BPFOOT_NUMOF_SENSORS) pressure sensors, 6 on the sole and 2 on the toe. Sensor order is left to right, top to bottom, starting at the front of the sole to the back of the heel, then the left and right toe sensors. dev_cmd_id: BSPROXY_BPFOOT_CMDID_GET_RAW

client device command body

no body

server pass response body

press_raw_vec u16 8 raw sensor pressure values

Get Calibrated Foot Data - Get the BrainPack Foot calibrated sensor readings. There are 8 (BSPROXY_BPFOOT_NUMOF_SENSORS) pressure sensors, 6 on the sole and 2 on the toe. Sensor order is left to right, top to bottom, starting at the front of the sole to the back of the heel, then the left and right toe sensors. dev_cmd_id: BSPROXY_BPFOOT_CMDID_GET_COOKED

client device command body

no body

server pass response body

press_cal_vec u16 8 calibrated sensor pressure values

---

BrainPack IMU Client-Server Messages

The BrainPack Inertia Measurement Unit (IMU) proxied device is an attached I²C Bus device with an application specific message set. All specific communication with the foot is through the Proxied Device Command.

Get IMU IDs - Get the BrainPack device identifiers. dev_cmd_id: BSPROXY_BPIMU_CMDID_GET_IDS

client device command body

no body

server pass response body

dev_id u16 1 BrainPack device id version u8 1 firmware version

Set IMU Orientation - Set the BrainPack IMU x-y-z orientation. The sensor read-out is always x-y-z order. However, the labeling of the axes are set by the orientation which specifies a set of coordinate rotations. dev_cmd_id: BSPROXY_BPIMU_CMDID_SET_ORIENT

client device command body

orientation u8 1 x-y-z orientation of the IMU

server pass response body

no body

Calibrate IMU - Calibrate BrainPack IMU sensors. Currently this is not defined and needs investigation. dev_cmd_id: BSPROXY_BPIMU_CMDID_CAL

client device command body

no body

server pass response body

no body

Get Raw IMU Data - Get the BrainPack IMU raw sensor readings. There are 3 (BSPROXY_BPIMU_NUMOF_SENSORS) orthogonal acceleration sensors in the x-y-z direction. Sensor order is x, y, z, rotated by orientation. dev_cmd_id: BSPROXY_BPIMU_CMDID_GET_RAW

client device command body

no body

server pass response body

accel_raw_vec u8 3 raw sensor acceleration values

Get Calibrated IMU Data - Get the BrainPack IMU calibrated sensor readings. There are 3 (BSPROXY_BPIMU_NUMOF_SENSORS) orthogonal acceleration sensors in the x-y-z direction. Sensor order is x, y, z, rotated by orientation. dev_cmd_id: BSPROXY_BPIMU_CMDID_GET_COOKED

client device command body

no body

server pass response body

accel_cal_vec u8 3 calibrated sensor acceleration values

---

BrainPack Hand Client-Server Messages

TBD

---

BrainPack Compass Client-Server Messages

TBD

---

RS-232 Controller Client-Server Messages

TBD

---

RCB-3 Controller Client-Server Messages

The RCB-3 controller provides real-time servo control for several robotic platforms, including the KHR-2 and MANOI AT01. All specific communication with the foot is through the Proxied Device Command.

See the RoadNarrows Robotics RCB3 package for more information.

The RCB-3 API header files are rcb3/rcb3prot.h and rcb3/rcb3lib.h

Get RCB-3 Version - Get the version of the RCB-3 controller. dev_cmd_id: RCB3CmdIdGetVersion

client device command body

no body

server pass response body

version zstr 1 version string

Get Servo Positions - Get the robot current servo positions. Get the current angular positions of all 24 (RCB3_PORT_NUM_MAX) servos. The order is relative to the robotic platform. dev_cmd_id: RCB3CmdIdGetCurPos

client device command body

no body

server pass response body

pos_raw_vec u16 24 raw position vector

Move Servo - Move a servo. The servo is rotated to the given end angular position at the give speed. The specified servo number is relative the specific robotic platform. dev_cmd_id: RCB3CmdIdMoveServo

client device command body

servo u8 1 servo number pos u16 1 raw end position value speed u8 1 unitless speed value

server pass response body

no body

Playback - Play a motion or scenario. The motion or scenario is stored in the RCB-3 controller's EEPROM. dev_cmd_id: RCB3CmdIdPlay

client device command body

play_index u8 1 motion/scenario play index

server pass response body

no body

Motion Stop - Stop all servos. dev_cmd_id: RCB3CmdIdStop

client device command body

no body

server pass response body

no body

---