Serial Communication: Difference between revisions

From STorM32-BGC Wiki V1
Jump to navigation Jump to search
(Created page with "The information on this page refers to firmware v0.56 and higher. <div class="toclimit-2">__TOC__</div> == Serial Communication Protocol == The protocol for the communicatio...")
 
No edit summary
Line 83: Line 83:
The checksum for protecting some data streams is the x25 16-bit crc used by [http://qgroundcontrol.org/mavlink/start Mavlink]. C code can be found [http://mbed.org/users/shimniok/code/AVC_2012/file/826c6171fc1b/MAVlink/include/checksum.h here].
The checksum for protecting some data streams is the x25 16-bit crc used by [http://qgroundcontrol.org/mavlink/start Mavlink]. C code can be found [http://mbed.org/users/shimniok/code/AVC_2012/file/826c6171fc1b/MAVlink/include/checksum.h here].


== Mavlink Communication ==
== Mavlink RC Communication ==
In addition to the serial commands described in the previous section, the o323bgc firmware also understands some "Mavlink" messages, which are intended to be used for remote control of the gimbal. These messages are actually not real Mavlink messages in the sense that they would work in a [http://qgroundcontrol.org/mavlink/start Mavlink] environment. They use however the [http://qgroundcontrol.org/mavlink/start#packet_anatomy Mavlinkdata packet structure].
In addition to the serial commands described in the previous section, the o323bgc firmware also understands some "Mavlink"-type messages, which are intended for remote control of the gimbal. These messages are not real Mavlink messages in the sense that they would work in a [http://qgroundcontrol.org/mavlink/start Mavlink] environment, but use the [http://qgroundcontrol.org/mavlink/start#packet_anatomy Mavlinkdata packet structure]. This set of commands shall be referred to as "Mavlink RC" commands.


The long-term intention is obviously to implement a full Mavlink support. Unfortunately, the author of the firmware doesn't yet understand Mavlink well enough to understand how to integrate a gimbal into a Mavlink system, hence the present first steps. Anyone with a deeper knowledge on Mavlink is highly welcome to join the rcgroups thread.
The rules of the communication are as before, the STorM32 controller emits a message only upon request, but never by itself, and any received message is acknowledged by a message send to the host. For messages from the host to the controller the SystemID is 'R' (= 0x52) and for messages from the controller to the host it is 'G' (= 0x47). The ComponentID is 'C' (= 0x43) in both cases.
 
The rules of the communication are as before, the STorM32 controller emits a message only upon request but never by itself, and any received message is acknowledged by a message send to the host. For messages from the host to the controller the SystemID is 'R' (= 0x52) and for messages from the controller to the host it is 'G' (= 0x47). The ComponentID is 'C' (= 0x43) in both cases.


The following commands can be send to the STorM32 controller:
The following commands can be send to the STorM32 controller:

Revision as of 19:48, 9 February 2015

The information on this page refers to firmware v0.56 and higher.

Serial Communication Protocol

The protocol for the communication via the serial interfaces (USB, UART, Bluetooth) follows these rules:

  • The board responds to incoming commands by sending back a data stream of one or more characters, which is determined by the recieved command.
  • The board is never sending/transmitting anything by itself, that is, a transmission is always started only as a reaction to an incoming command.
  • The board is responding to any incoming command, be it valid or not.


Any data stream returned by the board ends with one of these characters:

  • 'o': indicates that everything is ok, i.e. that the recieved command has been identified
  • 'e': indicates that an error has occured, i.e. that an invalid command has been recieved
  • 't': indicates that a timeout has occured, i.e. that a command which consists of several characters was not completed within a certain time window
  • 'c': indicates that a checksum error has occured


A checksum is invoked only for some few commands, currently the 'p','g', and 'd' commands. The reason is that a checksum is certainly desirable from a security point of view, but quite inconvenient for hands-on communication via terminals etc., which is usefull for development.

Command 't'

This command simply returns the character 'o'. Can be used by the host to check if the board is still connected.

Command 'v'

This command returns information on the installed firmware version, the name of the board, and the type of the board. The data stream is appended by a crc, and closed with the character 'o'.

Command 'g'

This command returns a data stream containing all parameter values. The data stream is appended by a crc, and closed with the character 'o'.

Command 'p'

This command sets all parameter values. The command character 'p' needs to be followed by a data stream containing all parameter values, plus a crc. It returns the character 'o'.

Command 'd'

Upon receipt of the command 'd' a data stream containing the current live data is transmitted. The live data is appended by a crc, and closed with the character 'o'. The respective C code snippet is as follows:

 //send 32 data values
 uart_prepare_transmit();
 ((u16*)fbuf)[(*len)++]= STATE; //state
 ((u16*)fbuf)[(*len)++]= status; //status
 ((u16*)fbuf)[(*len)++]= status2; //status2
 ((u16*)fbuf)[(*len)++]= i2c_geterrorcntofdevice(IMU_I2CDEVNR)+i2c_geterrorcntofdevice(IMU2_I2CDEVNR);
 ((u16*)fbuf)[(*len)++]= adc_lipovoltage(); //lipo_voltage;
 ((u16*)fbuf)[(*len)++]= (u16)systicks; //timestamp
 ((u16*)fbuf)[(*len)++]= (u16)(1.0E6*fdT); //cycle time
 ((u16*)fbuf)[(*len)++]= (s16)(fImu1.imu.gx);
 ((u16*)fbuf)[(*len)++]= (s16)(fImu1.imu.gy);
 ((u16*)fbuf)[(*len)++]= (s16)(fImu1.imu.gz);
 ((u16*)fbuf)[(*len)++]= (s16)(10000.0f*fImu1.imu.ax);
 ((u16*)fbuf)[(*len)++]= (s16)(10000.0f*fImu1.imu.ay);
 ((u16*)fbuf)[(*len)++]= (s16)(10000.0f*fImu1.imu.az);
 ((u16*)fbuf)[(*len)++]= (s16)(10000.0f*fImu1AHRS.R.x);
 ((u16*)fbuf)[(*len)++]= (s16)(10000.0f*fImu1AHRS.R.y);
 ((u16*)fbuf)[(*len)++]= (s16)(10000.0f*fImu1AHRS.R.z);
 ((u16*)fbuf)[(*len)++]= (s16)(100.0f*fImu1Angle.Pitch);
 ((u16*)fbuf)[(*len)++]= (s16)(100.0f*fImu1Angle.Roll);
 ((u16*)fbuf)[(*len)++]= (s16)(100.0f*fImu1Angle.Yaw);
 ((u16*)fbuf)[(*len)++]= (s16)(100.0f*cPID[PITCH].Cntrl);
 ((u16*)fbuf)[(*len)++]= (s16)(100.0f*cPID[ROLL].Cntrl);
 ((u16*)fbuf)[(*len)++]= (s16)(100.0f*cPID[YAW].Cntrl);
 ((u16*)fbuf)[(*len)++]= InputSrc.Pitch;
 ((u16*)fbuf)[(*len)++]= InputSrc.Roll;
 ((u16*)fbuf)[(*len)++]= InputSrc.Yaw;
 ((u16*)fbuf)[(*len)++]= (s16)(100.0f*fImu2Angle.Pitch);
 ((u16*)fbuf)[(*len)++]= (s16)(100.0f*fImu2Angle.Roll);
 ((u16*)fbuf)[(*len)++]= (s16)(100.0f*fImu2Angle.Yaw);
 ((u16*)fbuf)[(*len)++]= (s16)(100.0f*fMag2Angle.Yaw);
 ((u16*)fbuf)[(*len)++]= (s16)(100.0f*fMag2Angle.Pitch);
 ((u16*)fbuf)[(*len)++]= (s16)(10000.0f*fImu1AHRS._imu_acc_confidence);
 ((u16*)fbuf)[(*len)++] = pack_functioninputvalues(&FunctionInputPulse);
 (*len)*=2;
 //add crc
 uint16_t crc= do_crc( fbuf, fbuf_len );
 fbuf[fbuf_len++]= (u8)crc; //low byte
 fbuf[fbuf_len++]= (u8)(crc>>8); //high byte
 //end character
 uart_transmit_ackchar( closewith ); //this sends a 'o'

Command 's'

Upon receipt of the command 's' a data stream containing the current status data is transmitted. The data stream is appended by a crc, and closed with the character 'o'. The command is essentially identical to the 'd' command, except that it transmits only the first five data values.

Checksum

The checksum for protecting some data streams is the x25 16-bit crc used by Mavlink. C code can be found here.

Mavlink RC Communication

In addition to the serial commands described in the previous section, the o323bgc firmware also understands some "Mavlink"-type messages, which are intended for remote control of the gimbal. These messages are not real Mavlink messages in the sense that they would work in a Mavlink environment, but use the Mavlinkdata packet structure. This set of commands shall be referred to as "Mavlink RC" commands.

The rules of the communication are as before, the STorM32 controller emits a message only upon request, but never by itself, and any received message is acknowledged by a message send to the host. For messages from the host to the controller the SystemID is 'R' (= 0x52) and for messages from the controller to the host it is 'G' (= 0x47). The ComponentID is 'C' (= 0x43) in both cases.

The following commands can be send to the STorM32 controller:

CMD_GETVERSION (#1)

0xFE 0x00 0x00 0x52 0x43 0x01 crc-low-byte crc-high-byte

If an error occurred a CMD_ACK message will be emitted. Otherwise a message containing the firmware version, the setup layout version and board capabilities in this format will be emitted:

0xFE 0x06 0x00 0x47 0x43 0x00 data1-low data1-high data2-low data2-high data3-low data3-high crc-low-byte crc-high-byte

Data1 is the firmware version, data2 the setup layout version, and data3 holds the board capabilities value.

CMD_GETVERSIONSTR (#2)

0xFE 0x00 0x00 0x52 0x43 0x02 crc-low-byte crc-high-byte

If an error occurred a CMD_ACK message will be emitted. Otherwise a message containing the version string, name string and board string in this format will be emitted:

0xFE 0x30 0x00 0x47 0x43 0x02 data-stream crc-low-byte crc-high-byte

The data stream contains the 16 bytes version string, the 16 bytes name string and the 16 bytes board string.

CMD_GETPARAMETER (#3)

0xFE 0x02 0x00 0x52 0x43 0x03 data-low-byte data-high-byte crc-low-byte crc-high-byte

The data is of type uint16_t and represents the number of the parameter which is requested. If an error occurred a CMD_ACK message will be emitted. Otherwise a message containing the parameter value in this format will be emitted:

0xFE 0x04 0x00 0x47 0x43 0x03 data1-low-byte data1-high-byte data2-low-byte data2-high-byte crc-low-byte crc-high-byte

Data1 is the parameter number and data2 holds the parameter value.

CMD_SETPARAMETER (#4)

0xFE 0x04 0x00 0x52 0x43 0x04 data1-low-byte data1-high-byte data2-low-byte data2-high-byte crc-low-byte crc-high-byte

Data1 is the parameter number and data2 holds the parameter value. As response to this command a CMD_ACK message will be emitted.

CMD_GETDATA (#5)

0xFE 0x01 0x00 0x52 0x43 0x03 type-byte crc-low-byte crc-high-byte

Type specifies the type of the requested data stream; currently only type 0 is supported. If an error occurred a CMD_ACK message will be emitted. Otherwise a message containing the data stream in this format will be emitted:

0xFE 0x40 0x00 0x47 0x43 0x05 type-byte 0x00 data-stream crc-low-byte crc-high-byte

The data stream contains the same data as send by the 'd' command.

CMD_GETDATAFIELD (#6)

0xFE 0x02 0x00 0x52 0x43 0x06 data-low-byte data-high-byte crc-low-byte crc-high-byte

The data is of type uint16_t and represents the number of the data field which is requested. If an error occurred a CMD_ACK message will be emitted. Otherwise a message containing the parameter value in this format will be emitted:

0xFE 0x04 0x00 0x47 0x43 0x06 data1-low-byte data1-high-byte data2-low-byte data2-high-byte crc-low-byte crc-high-byte

Data1 is the data field number and data2 holds the data field value.

CMD_SETPITCH (#10)

0xFE 0x02 0x00 0x52 0x43 0x0A data-low-byte data-high-byte crc-low-byte crc-high-byte

The data is of type uint16_t and can assume the values 1000...2000. If the value 0 is send, then the pitch axis will be recentered to zero if in "relative" mode. As response to this command a CMD_ACK message will be emitted.

CMD_SETROLL (#11)

0xFE 0x02 0x00 0x52 0x43 0x0B data-low-byte data-high-byte crc-low-byte crc-high-byte

The data is of type uint16_t and can assume the values 1000...2000. If the value 0 is send, then the roll axis will be recentered to zero if in "relative" mode. As response to this command a CMD_ACK message will be emitted.

CMD_SETYAW (#12)

0xFE 0x02 0x00 0x52 0x43 0x0C data-low-byte data-high-byte crc-low-byte crc-high-byte

The data is of type uint16_t and can assume the values 1000...2000. If the value 0 is send, then the yaw axis will be recentered to zero if in "relative" mode. As response to this command a CMD_ACK message will be emitted.

CMD_SETPANMODE (#13)

0xFE 0x01 0x00 0x52 0x43 0x0D data-byte crc-low-byte crc-high-byte

The data is of type uint8_t and can assume these values: 0 = off, 1 = HOLDHOLDPAN, 2 = HOLDHOLDHOLD, 3 = PANPANPAN, 4 = PANHOLDHOLD, 5 = PANHOLDPAN. As response to this command a CMD_ACK message will be emitted.

CMD_SETSTANDBY(#14)

0xFE 0x01 0x00 0x52 0x43 0x0E data-byte crc-low-byte crc-high-byte

The data is of type uint8_t and can assume these values: 0 = off, 1 = on. As response to this command a CMD_ACK message will be emitted.

CMD_DOCAMERA(#15)

0xFE 0x06 0x00 0x52 0x43 0x0F dummy-byte data-byte dummy-byte dummy-byte dummy-byte dummy-byte crc-low-byte crc-high-byte

The data is of type uint8_t and can assume these values: 0 = off, 1 = IRSHUTTER, 2 = IRSHUTTERDELAYED, 3 = IRVIDEOON, 4 = IRVIDEOOFF. As response to this command a CMD_ACK message will be emitted.

CMD_SETSCRIPTCONTROL (#16)

0xFE 0x02 0x00 0x52 0x43 0x10 data1-byte data2-byte crc-low-byte crc-high-byte

The data1 and data2 are of type uint8_t. Data1 is the number of the script and data2 can assume these values: 0 = off, 1 = CASE#DEFAULT, 2 = CASE#1, 3 = CASE#2, 4 = CASE#3. As response to this command a CMD_ACK message will be emitted.

CMD_ACTIVEPANMODESETTING (#100)

0xFE 0x01 0x00 0x52 0x43 0x64 data-byte crc-low-byte crc-high-byte

The data is of type uint8_t and is a bit field related to the pan mode setting: default setting = 0x00, setting #1 = 0x01, setting #2 = 0x02, setting #3 = 0x03. As response to this command a CMD_ACK message will be emitted.

CMD_ACK (#150)

0xFE 0x01 0x00 0x47 0x43 0x96 data-byte crc-low-byte crc-high-byte

This command is returned by the STorM32 controller to acknowledge execution of a received message (if the message itself doesn't lead to a response, such as get parameter command). The data is of type uint8_t and can assume these values:

0 = MAV_CMD_ACK_OK=0

1 = MAV_CMD_ACK_ERR_FAIL

2 = MAV_CMD_ACK_ERR_ACCESS_DENIED

3 = MAV_CMD_ACK_ERR_NOT_SUPPORTED

150 = MAV_CMD_ACK_ERR_TIMEOUT

151 = MAV_CMD_ACK_ERR_CRC

152 = MAV_CMD_ACK_ERR_PAYLOADLEN