UKHAS Wiki

UK High Altitude Society

User Tools

Site Tools


communication:protocol

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
communication:protocol [2010/04/16 22:16]
danielrichman
communication:protocol [2015/04/03 09:49] (current)
mfa298 removed eroneous , at the end of the example
Line 1: Line 1:
 ====== Communications Protocol ====== ====== Communications Protocol ======
  
-This is the typical protocol used by UKHAS members to transmit GPS data balloon to ground on the unlicensed bands, although any custom data may be tacked onto the end of the string.+This is the typical protocol used by UKHAS members to transmit GPS data balloon to ground on the unlicensed bands. Parsing is handled by [[http://​habitat.habhub.org/​|habitat]] which can be configured to almost practically any format you can come up with, provided ​the string ​starts with $$CALLSIGN, end with a newline ('​\n'​),​ and contains printable ASCII characters. Fields are comma delimited.
  
-This doesn'​t have to be strictly adhered tosince we can easily set up different rules via [[projects:​dl-fldigi]]'​s ability to automatically configure itself (upon request).+ <​code>​ $$CALLSIGN,sentence_id,​time,​latitude,​longitude,​altitude,​optional speed,​optional bearing,​optional internal temperature*CHECKSUM\n </​code>​
  
-  ​$$<CALL SIGN>,<COUNTER D>,<​TIME HH:​MM:​SS>,<​LATITUDE DD.DDDDDD>,<​LONGITUDE DD.DDDDDD>,<​ALTITUDE METRES MMMMM>,<O SPEED KM/H DDDD.DD>,<​O BEARING DDD.DD>,<O TEMPERATURE INTERNAL C D.DD>,<O TEMPERATURE EXTERNAL C D.DD>,<O TEMPERATURE CAMERA C D.DD>,<O BAROMETRIC PRESSURE hPa(millibars)>​,<O CUSTOM DATA>*<​CHECKSUM><​NEWLINE>​+  ​* The individual fields can be of variable lengththe minimum and maximum can be set in the payloads XML file. 
 +  * CALLSIGN simply identifies your balloon - doesn'​t have to be a reallicensed callsign 
 +  * sentence_id (sometimes known as countsequenceincremental counter...) also helps people receiving many transmissions at once. This should go up for each new transmission. It can go up 1, 2, 3, or be the milliseconds since power onor whatever you wantIt just has to increase each time a new string is sent. 
 +  * latitude and longitude can either be in decimal degrees (DD.dddd) or the NMEA format (DDMM.mmmm). If using decimal degrees take care that your conversion code does not break if it crosses the meridian. While the NMEA format is accepted you will still need to parse whether it its NSEW and use +/- appropriately. 
 +  * The checksum is very strongly recommended. We support CRC16_CCITTNMEA XOR and a couple of variants of Fletcher 16 checksums; however: the CRC16_CCITT is the most popular and is far better than xor, which is mainly supported for old payloadsThere have actually been real xor collisions. 
 +  * The newline at the end IS required. It does make the protocol much more easier to human-readand dl-fldigi looks for that character to terminate the stringAlthough both will workplease use '​\n'​not '​\r\n'​. 
 +  ​Here are example strings:
  
-  ​* <CALL SIGN> simply identifies your balloon - doesn't have to be a real, licensed callsign. ​ +  ​XOR Checksum'd string: 
-  ​* <​INCREMENTAL COUNTER ID> also helps people receiving many transmissions at once. This should go up for each new transmission. It can go up 123or be the milliseconds since poweron, or whatever you wantIt just has to increase each time a new string is sent. +  ​$$A1,15254,15:36:34,52.145255,000.542061,00118,​0000,​03,3F4D3F2F,45*62
-  * The checksum is optionalbut not for much longer! :)It must either be the NMEA XOR format or the CRC16_CITT +
-  * After "<​ALTITUDE>​," the distributed tracker or anyone else not prepared for your custom data will not plot your data however the DL system will log the data for review. If you want to send anything else downyou can do so in that space. +
-  ​The newline at the end IS required. It does make the protocol much more easier to human-read, and dl-fldigi looks for that character to terminate the string.+
  
-  ​* Here are example strings:+  ​Example of a CRC16_CCITT'​d string: 
 +  $$hadie,​181,​10:​42:​10,​54.422829,​-6.741293,​27799.3,​1:​10*002A
  
-  $$ALIEN1,1,12:13:11,50.904072,00.026106,09001,temperature:​ 14+  ​Demonstration of the fact that the custom data can be anything: 
 +  ​$$icarus,12342,12:34:17,52.345645,-1.02342,10232,21.35,​192.3,​15.4,​-22.34,​-18.27,​1232,​Blah,​Blah,​Blah*0C
  
-  $$icarus,​12342,​12:​34:​17,​52.345645,-1.02342,​10232,​21.35,​192.3,​15.4,​-22.34,​-18.27,​1232+**Usage example for the below two functions** 
 +<code c>#​include <stdio.h> 
 +#include <stdint.h> 
 +#include <string.h>
  
-  ​$$icarus,12342,12:34:17,52.345645,-1.02342,10232,21.35,192.3,15.4,-22.34,-18.27,1232,Blah;Blah;​Blah*00+char s[100]; 
 + 
 +void make_string(struct information i) 
 +
 + char checksum[10];​ 
 + 
 + snprintf(s,​ sizeof(s), "$$MYPAYLOAD,%i,%s,%s", i->num, i->gps.lati->gps.lon); 
 + 
 + snprintf(checksumsizeof(checksum)"​*%04X\n"​gps_CRC16_checksum(s));​ 
 + // or snprintf(checksumsizeof(checksum)"​*%02X\n"​gps_xor_checksum(s));​ 
 + 
 + // It would be much more efficient to use the return value of snprintf here, rather than strlen 
 + 
 + if (strlen(s) > sizeof(s) ​4 - 1) 
 +
 + // Don't overflow the buffer. You should have made it bigger. 
 + return; 
 +
 + 
 + // Also copy checksum'​s terminating \0 (hence the +1). 
 + memcpy(s + strlen(s)checksumstrlen(checksum) + 1); 
 +}</​code>​
  
 **Useful code to calculate NMEA xor checksum** **Useful code to calculate NMEA xor checksum**
 +
 +Please note: The use of xor checksum for payload telemetry is not advised, this code is useful for checking sentences sent by the GPS. The CCITT checksum below has much better performance and is preferred for payload telemetry
  
 <code c>#​include <​stdio.h>​ <code c>#​include <​stdio.h>​
 #include <​stdint.h>​ #include <​stdint.h>​
 +#include <​string.h>​
  
-sprintf (checksum, "​*%02X\n",​ gps_checksum(string));​ +uint8_t ​gps_xor_checksum(char *string)
- +
-unsigned ​uint8_t ​gps_checksum ​(char * string)+
 { {
- unsigned ​size_t i; + size_t i; 
- unsigned ​uint8_t XOR; + uint8_t XOR; 
- unsigned ​uint8_t c;+ uint8_t c;
  
  XOR = 0;  XOR = 0;
Line 47: Line 77:
  
 **Useful code to calculate CRC16_CCITT checksum on the AVR** **Useful code to calculate CRC16_CCITT checksum on the AVR**
 +
 +(Refer to [[http://​www.nongnu.org/​avr-libc/​user-manual/​group__util__crc.html#​gaca726c22a1900f9bad52594c8846115f | this page]] for implementation on other microcontrollers)
  
 <code c>#​include <​stdio.h>​ <code c>#​include <​stdio.h>​
 #include <​stdint.h>​ #include <​stdint.h>​
 #include <​util/​crc16.h>​ #include <​util/​crc16.h>​
 +#include <​string.h>​
  
-sprintf (checksum, "​*%04X\n",​ gps_checksum(string));​ +uint16_t gps_CRC16_checksum (char *string)
- +
-unsigned ​uint16_t gps_CRC16_checksum (char * string)+
 { {
- unsigned ​size_t i; + size_t i; 
- unsigned ​uint16_t crc; + uint16_t crc; 
- unsigned ​uint8_t c;+ uint8_t c;
  
  crc = 0xFFFF;  crc = 0xFFFF;
Line 71: Line 102:
  return crc;  return crc;
 }</​code>​ }</​code>​
 +====== Getting Your Payload On the Tracker ======
  
 +You will need to fill out a flight document so the server can parse your telemetry strings and update the map.\\ ​
 +Fill out the form here :​[[http://​habhub.org/​genpayload/​|Payload Document Generator]] the come and see us on [[ukhas:​irc_channel|IRC]] to get it added.
communication/protocol.1271456181.txt.gz · Last modified: 2010/04/16 22:16 by danielrichman