Skip to content

Saving, Storing, Sending Messages

Jump to bottom
Linkesh Diwan edited this page Jan 30, 2014 · 7 revisions

This page gives a low-down view of what types of messages ("records") we have, and what types of fields we have, and how everything fits together.

In GIS parlance, our "records" are essentially "map assets", or items on the map. There are many different types of records, each type has it's own set of required and recommended fields. The definition of a record is known as a record template. Many record templates have been formulated as below. We can support up to 0xFF record templates, or 256 different types of records.

Each record, when entered on the map in one device, is transferred via APRS messages to the other devices in the network.

Every record is displayed on the map as an icon (displayed icons need to have a filtering mechanism - TODO)

When accessing a record on the map, it's summary of required and recommended fields are displayed, as well as any response messages (type F0) that reference it.

If a record is "deleted", it is marked as such and removed from the map display, however it will persist in the database, and can be resurrected if need be. It's data will be disregarded by any analysis functions built into the device.

Table of Contents

APRS message

What is APRS and what do we use it for? APRS is a messaging specification built for connectionless networks. http://aprs.org/

We are using the APRS to send data from one device to another.

So, what happens is:

  • User enters data.
  • Data is saved as a record to the database on the user's machine.
  • The Database Sync daemon formulates the new record into an APRS message (as below), and puts the message into a transmit queue.
  • Another program (to be written) takes messages from the queue and transmits them across the network. This is not part of this challenge.
  • Another program (to be written) listens to the network, and writes down the messages it hears and puts them into a receive queue.
  • The Database Sync daemon monitors the receive queue, and inserts messages from it after validating (see the Database Sync Daemon page).
The structure of the APRS message is detailed here.

(< op_id >;< s_dev_id >;< ts >;< gps >;) < r_type >;< nparams >;<( paramID , value)>;<( paramID , value)>; ... 

 op_id: Sender Operator ID

 s_dev_id: Sender device ID

 ts: Timestamp

 gps: GPS coordinates of the originating device 

 r_type: Type of record. Two Hexadecimal digits, total of 256 message types.

The type of record can be:

  • 0* : Network Control Messages e.g 01,02,...
  • 1* : Map based e.g. 11, 19
  • 2* : Person Register
  • 3* : Logistics / other
  • 4* : Emergency, Crime, Impending Disaster, etc.
  • ... Unallocated, may be dynamically allocated in the future
  • F* : Service Messages
Note: * indicates a hex digit. See Message types for detailed information. 
 nparams: number of parameters

 (paramID, value) : A tuple containing a parameter and its corresponding value. e.g (name,Abraham)

Record Templates Overview

Here we describe some of the different types of records that can be formulated.

Network Control messages : 0*

  • 00: New Record Template
  • 01: Update Record Template
  • 02: Device going offline
  • 03: Device Assignment
  • 04: Channel Change (reserved)
Maps : 1*
  • 10: Position Update (no message)
  • 11: Resources Available
  • 12: Refugee Center
  • 13: Road Assessment
  • 14: HAZMAT (chemical factories / spills / contaminated areas, etc)
People : 2*
  • 20: Refugee
  • 21: Missing
  • 22: Deceased
  • 23: Response Personnel
Logistics : 3*
  • 30: Headcount Order
  • 31: Headcount Report
  • 32: Rendezvous
  • 33: Supplies running low
Note: Logistics functions are more based on local data processing and local alerts than on messaging. Automatic logisitcs messages are mostly posted as responses to messages (F0)

Emergency, Crime, ... 4*

  • 40: Impending Disaster / Emergency / Help Needed
  • 41: Crime
Service Messages, F*
  • F0: Update Record
  • F1: Respond to Record
  • FE: General Announcement
  • FF: SOS call
Unassigned We are leaving the rest to be assigned later as the we iterate the development of the specification

Record Templates

Templates specify which, from a pool of parameters, are required, recommended, and optional parameters for a given type of record. In general, any parameter not specified explicitly in the record template is optional. Required and Recommended parameters must be easy to enter through the interface in as few steps as possible. (Provision must be made to have custom record types as well, but this may be reserved for future work.) It would be good to build the interface so that it formulates the input form by referencing the record template, this will aid in expanding the system.

For each record, based on the type of record there may be a list of parameters that are required, another list of parameters that are recommended, and all the other parameters may be optional. Each parameter represents a type of field on the user interface. For example, the following records and their required and recommended parameters.

00: New Record Template:

This is meant to dynamically extend the capabilities of the system. In the case that a new type of record needs to be created, for example, if we need to record the location of beached whales.

Required:

  • Record Template Name (eg: beached whale)
  • Record Template ID (automatically assigned)
  • Required Parameters for this template (CSV list of required parameters’ ID) (eg: GPS coordinates, name of beach)
  • Recommended Parameters for this template (CSV list of recommended parameters’ ID) (eg: health status, comments)

01: Update Record Template:

This is meant to dynamically tweak the system. Most probable use case is to demote a field from required to recommended to aid entry of information.

Required:

  • Record Template ID
  • Required Parameters (CSV list of required parameters’ ID) (eg: GPS coordinates)
  • Recommended Parameters (CSV list of recommended parameters’ ID) (eg: health status, comments)

02: Device going offline:

Meant to let other devices know who’s online or not. No required parameters.

Recommended:

  • Type of shutdown (low battery, normal powerdown)
  • Comments

03: Device Assignment:

This is to let other devices know that this device has been assigned a special role in the disaster.

Required:

  • Type of Assignment (Ambulance / Helicopter / Internet facing gateway / Incident Response Center / Refugee Center / Hospital / Morgue / New Record Template Block)
Recommended:
  • Comments

10: Position Update:

This is basically a periodic no-op message sent with the current position. This functionality may be handled in APRX directly, and may not need a user interface.

Required:

  • Current Position

11: Resources:

Required:

  • Type of Resource: (gas stations, medical supplies, food storage, buildings useful for refugee centers or morgues, potable water source, place of religious significance)
  • Condition of Resource (sliding scale from might be usable to perfect)
Recommended:
  • GPS location (if different from device’s location, point out on map)
  • Ownership (public / private but free to use / private but compensation requested / private and owner * unavailable / other)
  • Amount of resource (estimate)
  • address location (using local landmarks / street names / etc. )
  • Comment (if any)
  • Remove from Map (toggle, presumably it’s exhausted)

12: Refugee Center:

Meant to send data about refugee centers.

Required:

  • GPS location (may be different from device’s location)
  • Center Name
Recommended:
  • Type of Resource: (gas stations, medical supplies, food, potable water, place of religious significance)
  • Amount of resource (estimate)
  • Sanitary Conditions (fair, poor)
  • Number of refugees (M, W, children)
  • Comments
  • Remove from Map (toggle, presumably it’s abandonded)

13: Road Assessment:

Meant to provide information on roads that the logistics modules can use in intelligent vehicle routing, and that can be seen on the road.

Required:

  • GPS location (may be different from device’s location)
  • Assessment (sliding scale from “there is no road” to “rock-climbing” to “donky-can-pass” to “two wheeler” to “car” to “truck”.)
Recommended:
  • Comment / Alternate route
  • Remove from Map (toggle, presumably it’s fixed)

14: HAZMAT warnings:

Required:

  • GPS location (may be different from device’s location)
  • Assessment (irritating to lethal.)
Recommended:
  • Comments
  • Remove from Map (toggle, presumably it’s fixed)

20: Refugee parameters:

Required:

  • Person Name (if Unknown, please tag person with record number)
  • Age (with a toggle of Approximate or Exact)
  • Gender
  • Health status: healthy? minor wounds? broken bones? ambulatory (can-walk)? unconscious? (series of check-boxes?)
  • Current Location (refugee center ID / GPS coords / hospital) (layer for the map)
  • Person ID (auto-generated from op_id, s_dev_id, ts, and serial number)
Recommended:
  • Found GPS Address (point on map)
  • GPS Address (point on map)
  • address location (using local landmarks / street names / etc.)
  • Phone
  • Relatives, Note which ones are found in the database.
  • Comments

21: Missing Person parameters:

Required:

  • Person Name
  • Age (with a toggle of Approximate or Exact)
  • Gender
Recommended:
  • Last known position GPS (point on map)
  • Last Seen
  • address location (using local landmarks / street names / etc.)
  • Phone
  • Relatives, Note which ones are found in the database
  • Comments

22: Deceased parameters:

Required:

  • Deceased Name
  • Age (with a toggle of Approximate or Exact)
  • Gender
  • Person ID (auto-generated from op_id, s_dev_id, ts, and serial number)
Recommended:
  • Current Location (morgue ID) (layer for the map)
  • Found GPS Address (point on map)
  • Address / Phone Number (layer for the map)
  • Relatives, Note which ones are found in the database
  • Comments

23: Response Personnel parameters (normally not entered, unless they have a problem):

Required:

  • Person Name (if Unknown, please tag person with record number)
  • Age (with a toggle of Approximate or Exact)
  • Gender
  • Health status: healthy? minor wounds? broken bones? ambulatory (can-walk)? unconscious? (series of check-boxes?)
  • Current Location (refugee center ID / GPS coords / hospital) (layer for the map)
  • Person ID (auto-generated from op_id, s_dev_id, ts, and serial number)
Recommended:
  • Comments

30: Headcount Order:

Meant as an order to count response personnel, to make sure all are accounted for.

Required:

  • Comment

31: Headcount Report:

To report the results of a headcount

Required:

  • Comment
Recommended:
  • Reference to Response Personnel records (if they are entered)

32: Rendezvous:

To schedule a meeting of response personnel, and/or others.

Required:

  • GPS Location (point on the map)
  • Address (streets / landmarks)
  • Datetime of the meeting
Recommended:
  • Comments
  • Remove from Map (toggle, presumably it’s fixed)

33: Supplies running low:

This is an alert that can be raised by any refugee center / morgue / personnel

Required:

  • Type of Resource: (gas stations, medical supplies, food, potable water, place of religious significance)
  • GPS Location
Recommended:
  • Address (Streets / landmarks)
  • Amount of resource (estimate)
  • Comments
  • Remove from Map (toggle, presumably it’s fixed)

40: Impending disaster / help needed / emergency parameters

Required:

  • degree of severity (sliding scale)
  • Service required: Emergency Evacuation (number of people?) / Fire Force / Volunteers for a messy job / Medical help / other
  • GPS location (may be different from device’s location) (layer on Map)
Recommended:
  • address location (using local landmarks / street names / etc.)
  • Comment (if any)
  • Remove from Map (toggle, presumably it’s fixed)

41: Crime

Required:

  • GPS location (may be different from device’s location) (layer on Map)
Recommended:
  • Headcount of people involved (default to 0 = Unknown)
  • address location (using local landmarks / street names / etc.)
  • Comment (if any) would tell the nature of the crime (murder / sexual depravity / looting / arson / riotous behavior / etc)
  • Remove from Map (toggle, presumably it’s fixed)

F0: Update Record

Required:

  • Original record GID
  • List of Updated Parameters
=== F1: Response parameters === (note, in display, responses get tagged to the original message). NOTE: not to be used for direct messaging.

Required:

  • reference message GID (<op_id></op_id><s_dev_id></s_dev_id><ts></ts>)
Recommended:
  • CSV of related message GIDs to cross-link
  • response message (Comment) NOTE: Comment parameters are only appended, not replaced.
This is an example of the logistics functioning. When a missing person is found, or a person is missing someone, the device should check through it’s people lists, and try to find a match. If it finds one, it should raise a response on the missing person’s record.

FF: SOS Call

This option sends SOS calls.

Required:

  • GPS Location (note that in most cases, the GPS can be read from the devices internal GPS, but the option should be there to manually choose a place on the map.)
Recommended:
  • Comment
  • Remove from Map (toggle, presumably it’s fixed)


              


          



  
          

            


            
Clone this wiki locally