Developing for the Canute protocol

Developers can implement support for Canute using BRLTTY’s BrlAPI(https://github.com/Bristol-Braille/canute-ui/wiki#Using_Canute_as_a_display_with_PCs).

To implement support for the Canute protocol directly, without BrlAPI, see framing and commands below.

Protocol

The serial line is 9600 Baud, 8n1.

Framing

This packetises (frames) data on the wire in the same way as SDLC’s/HDLC’s/PPP’s asynchronous mode, but replacing that structuring of the payload with your own application-specific one. To be explicit on the detail, this code:

When choosing or writing something to talk to this at the other end of the link, note that:

Commands

Every command echos the command being responded to followed by any return data which is mostly just a status byte. On the status byte 0 indicates an ok status.

Command Name Code Data to Send Description Returns
COMMAND_N_CHARACTERS 0x00 Nothing Number of characters pair row in the hardware 1+3 bytes
COMMAND_N_ROWS 0x01 Nothing Number of rows on the display 1+2 bytes
COMMAND_VERSION 0x03 Nothing Outputs the protocol version 1+3 bytes
COMMAND_SEND_LINE 0x06 Braille data (see-below) Send the canute a row of braille to display 1+2 bytes (zeros)
COMMAND_RESET 0x07 Nothing Reset the display 1+2 bytes (zeros)
COMMAND_LOWER_ALL 0x09 Nothing Lowers the rods of all rows 1+2 bytes (zeros)
COMMAND_SEND_BUTTONS 0x0A Nothing Outputs the button presses (a-bit-field) 1+2 bytes
COMMAND_PMCU_FW_VERSION 0x0B Nothing Outputs the firmware version 1+variable length
COMMAND_POLL 0x0D Nothing Poll the status of Canute motion (sends-0b1-if-in-motion) 1+2 bytes
COMMAND_SET_LIFT_POSITION 0x0E 2 bytes - the row number Set the rod to up or down 1+2 bytes (zeros)

Braille Data

COMMAND_SEND_LINE is the most useful command. With the first byte you indicate the line number (0—8) your are trying to set followed by the Braille data.

Command Line number (0—8) Braille Data
Example: 0x06 0x01

Canute only supports 6-dot braille and it is encoded as integers 0-64 in a binary fashion.

Effectively this means we are using unicode braille minus 10240.

Additional Commands

You probably don’t need these.

Command Name Code Description Returns
COMMAND_SEND_PAGE 0x02 Deprecated 1+2 bytes
COMMAND_SEND_OK 0x05 Command the Canute to make a confirmation sound (currently-unused) 1+nothing
COMMAND_SEND_ERROR 0x04 Command the Canute to make an error sound (currently-unused) 1+nothing
COMMAND_TEST_MODE ascii ‘t’ Go into a test mode (currently-unused) 1+nothing

Useful links for reference (please-credit-as-appropriate-you-find-any-of-the-following-useful-in-writing-your-own-implementation): - brltty/Drivers/Braille/Canute/brldefs-cn.h(https://github.com/brltty/brltty/blob/master/Drivers/Braille/Canute/brldefs-cn.h) - brltty/Drivers/Braille/Canute/braille.c(https://github.com/brltty/brltty/blob/master/Drivers/Braille/Canute/braille.c)