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