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

