Overview

The Gramophone is a Raw-HID (Human Interface Device). It can send and receive 64 byte long packets (byte arrays). Numbers that take up multiple bytes are encoded in a little endian manner.

If you are implementing communication in Python you can use the GramophoneTools.Comms.Gramophone.Packet class to construct a packet.

Note: Some communication modules require a 65 byte long packet. In this case the extra byte should be in the begining and equal to 0.

Packet structure

Each of the sent and received packets have a the following structure:

packet[0:2] - Target
The 2 byte adress of the target of the packet. Can be anything. The response packet will have this as its Source
packet[2:4] - Source
The 2 byte adress of the source of the packet. Can be anything. The response packet will have this as its Target
packet[4] - MSN
A single byte that can be used for identification. The response packet will have the same MSN.
packet[5] - CMD
The 1 byte ID of the command. See commands below.
packet[6] - Payload length
A single byte that holds the length of the payload. The payload will only be evaluated to whis length.
packet[7:64] - Payload
The payload of the packet.

Commands

The possible user commands (values for packet[6]) are the following:

0x00 - Ping
Whatever payload is sent with this command will be sent back as a response.
0x01 - OK response
This is the command sent back after writing a parameter successfuly.
0x02 - FAILED response
This is the command sent back after writing a parameter failed. The payload is the errorcode (see below).
0x04 - Get firmware info
Get information about the firmware. The structure of the reply is explained below.
0x05 - Device state
Check the state of the device. The device should be in 0x01 state for usage. The 0x00 state is for setup.
0x06 - Store
Save persistent variables into the FLASH.
0x07 - Restore
Load persistent variables from the FLASH.
0x08 - Get product info
Get information about the product. The structure of the reply is explained below.
0x0B - Read parameter(s)
Read the value of the parameters given in the payload. The list of parameters are given below. More that one parameter can be read in one command. The order of the values in the response will be the same as the order of the parameters in the payload of this command.
0x0C - Write parameter
Write the parameter given by the first byte of the payload with the value that follows it.

Error codes

The codes received in the payload of a FAILED response packet can be the following:

0x00 - PACKET_FAIL_UNKNOWNCMD
Unknown command.
0x01 - PACKET_FAIL_INVALIDCMDSYNTAX
Invalid syntax.
0x04 - PACKET_FAIL_INVALIDPARAMSYNTAX
Invaid parameter syntax.
0x05 - PACKET_FAIL_RANGEERROR
Parameter out of range.
0x06 - PACKET_FAIL_PARAMNOTFOUND
Parameter not found.
0x07 - PACKET_FAIL_VALIDFAIL
Packet validation failed.
0x08 - PACKET_FAIL_ACCESSVIOLATION
Access to the parameter was violated (writing read only parameter).

Parameters

The following parameters can be read or written with the 0x0B and 0x0C commands:

0x01 - VSEN3V3 (float)
Voltage on 3.3V rail.
0x02 - VSEN5V (float)
Voltage on 5V rail.
0x03 - TSENMCU (float)
Internal teperature of the MCU.
0x04 - TSENEXT (float)
External temperature sensor on the board.
0x05 - TIME (uint64)
The time of the internal clock of the device in 0.1 ms steps.
0x10 - ENCPOS (int32)
Encoder position.
0x11 - ENCVEL (float + uint8)
Encoder velocity. The float part is the velocity of the disk, the integer is 1 if the disk is moving or 0 if it is not.
0x12 - ENCVELWIN (uint16)
Encoder velocity window size.
0x13 - ENCHOME (uint8)
Encoder homing. 0 if the encoder is not trying to find the home position, 1 if it is homing and 2 if the home position was found.
0x14 - ENCHOMEPOS (int32)
Encoder home position.
0x20 - DI-1 (uint8)
Digital input 1.
0x21 - DI-2 (uint8)
Digital input 2.
0x30 - DO-1 (uint8)
Digital output 1.
0x31 - DO-2 (uint8)
Digital output 2.
0x32 - DO-3 (uint8)
Digital output 3.
0x33 - DO-4 (uint8)
Digital output 4.
0x40 - AO (float)
Analogue output.
0xFF - LED (uint8)
On board LED state. 0 is off, 1 is on.

Firmware info structure

The firmware information received after sending the 0x04 command has the following structure.

payload[0] (uint8)
Release
payload[1] (uint8)
Subrelease
payload[2:4] (uint16)
Build
payload[4:6] (uint16)
Year
payload[6] (uint8)
Month
payload[7] (uint8)
Day
payload[8] (uint8)
Hour
payload[9] (uint8)
Minute
payload[10] (uint8)
Second

Product info structure

The product information received after sending the 0x08 command has the following structure:

payload[0:18] (char[18])
Name
payload[18:24] (char[6])
Revision
payload[24:28] (uint32)
Serial
payload[28:30] (uint16)
Product year
payload[30] (uint8)
Product month
payload[31] (uint8)
Product day