Merge branch 'master' of lab.iut-blagnac.fr:adrien/locapack

README.md

@@ -4,12 +4,59 @@
 
 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,
+1. Copy the `Arduino/LocaPack` directory into the libraries directory (typically `~/Arduino/libraries`)
+1. 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.
+
+![Drag Racing](nodered/node-red-flow-example.png)
+
+#### Installation
+
+1. Clone the LocaPack project,
+1. 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.
+1. Restart Node-RED.
+
 ### JSON messages
 
 LocaPack messages are also available in JSON. Example of a Universal GNSS localisation packet:
@@ -124,9 +171,9 @@ Transport of locally referenced 2D or 3D localisation. The "repère" is identifi
 
 ##### Payload general structure
 
-|    1B    | 4B  | 4B  | 0/4B | 0/4B  |    0/8B     |
-|----------|-----|-----|------|-------|-------------|
-| `header` | `x` | `y` |  `z` | `dop` | `repere_id` |
+|    1B    | 4B  | 4B  | 0/4B | 0/4B  |      0/8B       |
+|----------|-----|-----|------|-------|-----------------|
+| `header` | `x` | `y` |  `z` | `dop` | `frameofref_id` |
 
 The `x` field is a C-type float and is mandatory.
 
@@ -136,19 +183,19 @@ 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 `repere_id` field is a 64-bit UID 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
 
-|        1b         |         1b          |            1b              |    5b    |
-|-------------------|---------------------|----------------------------|----------|
-| `z_presence_flag` | `dop_presence_flag` |  `repere_id_presence_flag` | reserved |
+|        1b         |         1b          |               1b               |    5b    |
+|-------------------|---------------------|--------------------------------|----------|
+| `z_presence_flag` | `dop_presence_flag` |  `frameofref_id_presence_flag` | reserved |
 
 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 `repere_id_presence_flag` must be set to 1 if the `repere_id` 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