locapack

Brief

Another localisation packet protocol to send/receive localisation data over networks.

Details

LocaPack is an implementation of the locapack protocol used to send or receive various localisation data over wired and wireless networks.

LocaPack enables the transport of:

• universal GNSS localisation coordonates such as latitude/longitude data,
• locally referenced localisations, such as {x,y} positions in an indoor environment,
• inter-node proximity information such as ranging data.

Some extra features are also avalable, such as:

• automatic mapping/translation of coordonates between universal GNSS/locally referenced localisations,
• movement_id, that enables extra movement information based on another sensor (typically a local accelerometer),
• packet sequence numbering and local timestamping, to track positions and detect missing information,
• message hashing, to send shorter but incomplete payloads, to respect privacy.

Several implementations are available:

• Embedded: C++ class (Arduino library)
• Infrastrucure/IoT: Node-RED palette
• Portable: python

A Json description of the messages is also available.

Implementation

Implementation status:

• Arduino: encode/decode header, encode/decode universal GNSS packets ; example sketch with GPS receiver.
• Node-RED: decode header, decode universal GNSS packets

Arduino

LocaPack is available as an Arduino library, to produce or decode locapack messages.

Installation

1. Clone the LocaPack project,
2. Copy the Arduino/LocaPack directory into the libraries directory (typically ~/Arduino/libraries)
3. Launch Arduino IDE and start with one of the examples.

• tinygpsplus.ino: Make universal GNSS pakets with data from a hardware GPS receiver connected to the Serial1 port

Node-RED

LocaPack is available as a Node-RED Palette, ie a collection of nodes to produce or decode locapack messages.

Installation

1. Clone the LocaPack project,
2. In your Node-RED user directory, typically ~/.node-red, run: npm install <location of node module> where location is the path to the nodered folder of the git cloned repository.
3. Restart Node-RED.

JSON messages

LocaPack messages are also available in JSON. Example of a Universal GNSS localisation packet:

{
  "header": {
    "protocol_version": 1,
    "device_id_size": 2,
    "packet_type": 1,
    "movement_id_presence_flag": false,
    "timestamp_presence_flag": true
  },
  "sequence_number": 2746,
  "timestamp": 27850001,
  "device_id": 237,
  "payload": [192,49,131,47,66,150,8,165,63,154,153,18,67,164,112,157,63],
  "universalGnssPacket": {
    "header": {
      "altitude_presence_flag": true,
      "dop_presence_flag": true
    },
    "latitude": 43.878116607666016,
    "longitude": 1.2893245220184326,
    "altitude": 146.60000610351562,
    "dop": 1.2300000190734863
  }
}

License

Locapack is distributed under the GPLv3 license. Please refer to the LICENSE file.

Packet structure details

Message endianness is little endian.

Packet general structure

The sequence_number field is mandatory.

The timestamp field is optional and its presence is announced in the header. The timestamp field contains the number of milliseconds since the boot of the local system. There is no synchronisation between different nodes.

The movement_id field is optional and its presence is announced in the header.

The device_id field length is annouced in the header. A length of 0 means that the field is not present in the packet, for example if the device_id is the same as the source address of the packet.

The payload_len field contains the length of the payload.

The payload length depends on the packet_type annouced in the header.

Header structure

The protocol_version field indicates the version of the localisation packet used. This documentation describes the version #1 of the localisation packet protocol.

The device_id_size indicates the number of Bytes of the device_id field. A length of 0 means that no device_id is present in the packet.

The packet_type indicates the structure of the payload. These types of packet have been described:

• type 0 : Universal GNSS localisation
• type 1 : Locally referenced localisation
• type 2 : Inter-node proximity

The movement_id_presence_flag must be set to 1 if the movement_id field is present in the packet.

The timestamp_presence_flag must be set to 1 if the timestamp field is present in the packet.

Payload structure by packet type

Type 0 : Universal GNSS localisation

Transport of GNSS coordinates. Altitude and DOP are optionnal.

Payload general structure

The latitude field is a C-type float and is mandatory.

The longitude field is a C-type float and is mandatory

The altitude field is a C-type float and its presence is annouced in the header

The dop field is a C-type float and its presence is annouced in the header

Header

The altitude_presence_flag must be set to 1 if the altitude field is present in the packet.

The dop_presence_flag must be set to 1 if the dop field is present in the packet.

Type 1 : Locally referenced localisation

Transport of locally referenced 2D or 3D localisation. The "repère" is identified by an UID.

Payload general structure

The x field is a C-type float and is mandatory.

The y field is a C-type float and is mandatory

The z field is a C-type float and its presence is annouced in the header

The dop field is a C-type float and its presence is annouced in the header

The frameofref_id field is a 64-bit UID that identify the Frame of Reference ("le repère utilisé") and its presence is annouced in the header

Header

The z_presence_flag must be set to 1 if the z field is present in the packet (3D localisation).

The dop_presence_flag must be set to 1 if the dop field is present in the packet.

The frameofref_id_presence_flag must be set to 1 if the frameofref_id field is present in the packet.

Type 2 : Inter-node proximity

Transport of raw distances (rangings) between pairs of nodes. The ranging technology can be specified.