Home

Welcome to the WebServerAndClient wiki!

MQTT Message flow

Login

1. Connect to MQTT using username and password and Will as follows:

   • topic: user/{username}/client/{client-id}/status
   • payload: disconnected
   • qos: 2
   • retain: True

2. Subscribe to user/{username}/client/{client-id}/error to retrieve eventual errors.

3. Publish "online" to user/{username}/client/{client-id}/status with qos = 2 and retain = True.

4. Subscribe to settings to retrieve settings and defaults. Expected format is:

   {
     "ambulance_status": {
       "UK": "Unknown",
       "AV": "Available",
       "OS": "Out of service",
       "PB": "Patient bound",
       "AP": "At patient",
       "HB": "Hospital bound",
       "AH": "At hospital"
     },
     "ambulance_capability": {
       "B": "Basic",
       "A": "Advanced",
       "R": "Rescue"
     },
     "call_priority": {
       "A": "Resucitation"
       "B": "Emergent"
       "C": "Urgent"
       "D": "Less urgent"
       "E": "Not urgent"
       "O": "Omega"
     },
     "call_status": {
       "P": "Pending"
       "S": "Started"
       "E": "Ended"
     },
     // The status for the ambulance in the call
     "ambulance_call_status": {
       "R": "Requested"
       "O": "Onging"
       "I": "Interrupted"
       "C": "Completed"
     },
     "equipment_type": {
       "B": "Boolean",
       "I": "Integer",
       "S": "String"
     },
     "defaults": {
       "location": {
         "latitude": "32.5149",
         "longitude": "-117.0382"
       },
       "state": "BC",
       "city": "Tijuana",
       "country": "MX"
     }
   }
   

5. Subscribe to user/{username}/profile to retrieve ambulances and hospitals available. Expected format is:

   {
     "ambulances": [
       {
         "ambulance_id": 1,
         "ambulance_identifier": "BUD1234",
         "can_read": true,
         "can_write": true
       },
       {
         "ambulance_id": 2,
         "ambulance_identifier": "BUH4321",
         "can_read": true,
         "can_write": true
       },
       {
         "ambulance_id": 34,
         "ambulance_identifier": "BUH1111",
         "can_read": true,
         "can_write": true
       },
       {
         "ambulance_id": 35,
         "ambulance_identifier": "BUJ1616",
         "can_read": true,
         "can_write": true
       }
     ],
     "hospitals": [
       {
         "hospital_id": 34,
         "hospital_name": "Hospital Nuevo",
         "can_read": true,
         "can_write": true
       },
       {
         "hospital_id": 35,
         "hospital_name": "Hospital Viejo",
         "can_read": true,
         "can_write": true
       },
       {
         "hospital_id": 36,
         "hospital_name": "Another Hospital",
         "can_read": true,
         "can_write": true
       },
       {
         "hospital_id": 37,
         "hospital_name": "Yet another",
         "can_read": true,
         "can_write": true
       },
       {
         "hospital_id": 38,
         "hospital_name": "Uno mas",
         "can_read": true,
         "can_write": true
       }
     ]
   }
   

Additional handshake for ambulance MQTT clients

Log in and out of applications

1. Publish "ambulance login" to user/{username}/client/{client-id}/ambulance/{id}/status with qos = 2 when logging in.
2. Publish "ambulance logout" to user/{username}/client/{client-id}/ambulance/{id}/status with qos = 2 when logging out.

Requesting and streaming locations

1. Subscribe to ambulance/{id}/data
2. Publish {"location_client": client_id} to user/{username}/client/{client-id}/ambulance/{id}/data.
3. Start streaming locations when location_client in ambulance/{id}/data matches client_id.
4. Stop streaming locations when location_client in ambulance/{id}/data no longer matches client_id.
5. Publish {"location_client": ""} to user/{username}/client/{client-id}/ambulance/{id}/data to stop streaming data or hijack current streaming source.

Accepting calls

1. Make sure application is streaming location.
2. Subscribe to ambulance/{ambulance-id}/call/+/status
3. Wait for "Requested" in ambulance/{ambulance-id}/call/{call-id}/status and retrieve call-id.
4. Subscribe to call/{call-id}/data
5. Wait to retrieve data and prompt user to accept call.
6. Publish "Accepted" to user/{username}/client/{client-id}/ambulance/{ambulance-id}/call/{call-id}/status.
7. Receive "Ongoing" on ambulance/{ambulance-id}/call/{call-id}/status.
8. Publish patient bound (PB) as status to user/{username}/client/{client-id}/ambulance/{call-id}/data
9. Publish other status updates, e.g. at patient (AP), hospital bound (HB), etc, as status to user/{username}/client/{client-id}/ambulance/{call-id}/data.
10. When call is finished, publish "Finished" to user/{username}/client/{client-id}/ambulance/{ambulance-id}/call/{call-id}/status.
11. Receive "Completed" on ambulance/{ambulance-id}/call/{call-id}/status.
12. Unsubscribe to call/{call-id}/data

Rejecting calls

1. Follow steps 1.-5. as in "Accepting Calls".
2. Publish "Declined" to user/{username}/client/{client-id}/ambulance/{ambulance-id}/call/{call-id}/status.
3. Receive "Declined" on ambulance/{ambulance-id}/call/{call-id}/status.
4. Unsubscribe to call/{call-id}/data

Suspending calls

1. Follow steps 1.-8. as in "Accepting Calls".
2. Publish "Suspended" to user/{username}/client/{client-id}/ambulance/{ambulance-id}/call/{call-id}/status.
3. Receive "Requested" on ambulance/{ambulance-id}/call/{call-id}/status.
4. Unsubscribe to call/{call-id}/data

Additional handshake for hospital clients

1. Publish "online" to user/{username}/client/{client-id}/hospital/{id}/status with qos = 2 and retain = true when logging in.
2. Publish "offline" to clear user/{username}/client/{client-id}/hospital/{id}/status when logging out.

Retrieving information

1. Subscribe to ambulance/{id}/data to retrieve ambulance information. Expected format is:

   {
     "id": 2,
     "identifier": "BUH4321",
     "capability": "A",
     "status": "AV",
     "orientation": 0,
     "location": {
       "latitude": "32.51667385665262",
       "longitude": "-117.0299291610718"
     },
     "timestamp": null,
     "location_client": "clientUniqueId12345678",
     "comment": null,
     "updated_by": 1,
     "updated_on": "2018-01-17T01:15:45.972000Z"
   }
   

2. Subscribe to hospital/{id}/data to retrieve hospital information. Expected format is:

   {
     "id": 34,
     "number": "1234",
     "street": "Unknown Street",
     "unit": null,
     "neighborhood": null,
     "city": "Tijuana",
     "state": "BC",
     "zipcode": "92093",
     "country": "MX",
     "location": {
       "latitude": "32.5149",
       "longitude": "-117.0382"
     },
     "name": "Hospital Nuevo",
     "comment": null,
     "updated_by": 1,
     "updated_on": "2018-01-16T18:17:19.678000Z",
     "hospitalequipment_set": [
       {
         "hospital_id": 1,
         "equipment_id": 6,
         "equipment_name": "CT Scan",
         "equipment_type": "B",
         "value": "True",
         "comment": null,
         "updated_by": 9,
         "updated_on": "2018-04-20T04:00:52.164571Z"
       },
       {
         "hospital_id": 1,
         "equipment_id": 4,
         "equipment_name": "Number of Ventilators (ER)",
         "equipment_type": "I",
         "value": "5",
         "comment": null,
         "updated_by": 9,
         "updated_on": "2018-04-20T03:59:55.016004Z"
       }
     ]
   }
   

3. Subscribe to hospital/{id}/metadata to retrieve hospital equipment metadata information. Expected format is:

   [
     {
       "id": 2,
       "name": "Beds",
       "etype": "I",
       "toggleable": false
     }
   ]
   

4. Subscribe to hospital/{id}/equipment/{equipment-id}/data to retrieve hospital equipment information. Expected format is:

   {
     "hospital_id": 38,
     "equipment_id": 2,
     "equipment_name": "Beds",
     "equipment_etype": "I",
     "value": "132",
     "comment": null,
     "updated_by": 1,
     "updated_on": "2018-01-16T22:39:45.280000Z"
   }
   

5. Subscribe to call/{id}/data to retrieve call information. Expected format is:

   {
     "id": 3,
     "status": "AV",
     "details": null,
     "priority": "A",
     "number": 169,
     "street": "Unknown Street",
     "unit": null,
     "neighborhood': null,
     "city": "Tijuana",
     "state": "BC",
     "zipcode": "92093",
     "country": "MX",
     "location": {
       "latitude": "32.51667385665262",
       "longitude": "-117.0299291610718"
     },
     "created_at": "2018-01-17T00:00:45.972000Z"
     "pending_at": "2018-01-17T00:00:45.972000Z"
     "started_at": "2018-01-17T00:01:00.972000Z"
     "ended_at": "2018-01-17T02:15:45.972000Z"
     "comment": null,
     "updated_by": 1,
     "updated_on": "2018-01-17T01:15:45.972000Z",
     "ambulancecalltime_set": null,   //need modified
     "patient_set": [{"id": 345, "name": "A", "age": 37}]
   }
   

Updating information

1. Publish to user/{username}/client/{client-id}/ambulance/{id}/data to update ambulance information.

2. Publish to user/{username}/client/{client-id}/hospital/{id}/data to update hospital information.

3. Publish to user/{username}/client/{client-id}/hospital/{id}/equipment/{equipment-id}/data to update hospital equipment information.

Format is the same as shown in Section Retrieving information.

Logging out

1. Publish "offline" to user/{username}/client/{client-id}/status with qos = 1 and retain = True.

Correspondence between API calls and MQTT topics

Ambulances

METHOD	API	METHOD	MQTT	Description
GET	api/ambulance/	---	---	List of ambulances
POST	api/ambulance/	---	---	Create new ambulance
GET	api/ambulance/{id}/	SUB	ambulance/{id}/data	Get existing ambulance
PATCH/PUT	api/ambulance/{id}/	PUB	user/{username}/client/{client-id}/ambulance/{id}/data	Modify existing ambulance

Hospitals

METHOD	API	METHOD	MQTT	Description
GET	api/hospital/	---	---	List of hospitals
POST	api/hospital/	---	---	Create new hospital
GET	api/hospital/{id}/	SUB	hospital/{id}/data	Get existing hospital
PATCH/PUT	api/hospital/{id}/	PUB	user/{username}/client/{client-id}/hospital/{id}/data	Modify existing hospital

Hospital Equipment

METHOD	API	METHOD	MQTT	Description
GET	api/hospital/{id}/equipment/	---	---	List of hospital equipment
GET	api/hospital/{id}/equipment/{equipment__name}/	SUB	hospital/{id}/equipment/{equipment__name}/data	Get existing hospital equipment
PATCH/PUT	api/hospital/{id}/equipment/{equipment__name}/	PUB	user/{username}/client/{client-id}/hospital/{id}/equipment/{equipment__name}/data	Modify existing hospital equipment
GET	api/hospital/{id}/metadata/	SUB	hospital/{id}/metadata	Hospital equipment metadata

Profile

METHOD	API	METHOD	MQTT	Description
GET	api/user/{username}/profile/	SUB	user/{username}/profile	List of hospital and ambulance permissions

Settings

METHOD	API	METHOD	MQTT	Description
GET	api/settings/	SUB	settings	Retrieve settings and defaults

MQTT exclusive topics

METHOD	MQTT	Description
SUB	user/{username}/client/{client-id}/error	Error messages from django generated after successfully posting a message
SUB	user/{username}/client/{client-id}/status	Used to communicate connection status of client: "online" and "offline" should be posted at login and logout. "disconnected" should be posted as a will message in case of unexpected disconnection.