Messages flow examples (Messaging)

Server Application sends a message using SIP IDENTIFIER in the topic

{"msgId":"1","payload":{"amsgId":"24668","sip_id":"1004","msg":{"server_msg_status":"new","prio":"1","title":{"text":"Message prio 1","color":"02"},"status_icon":"0D","status_text":"accepted","ttl":"10","alert_info":"msg_melody_low","overrule_silencing":"no","vibration":"no","ringtone_volume":"50","presentation_time":"10","deletable":"yes","local_ignore":"yes","body_starter":"Body starter","msg_icon":{"value":"1f"},"body":[{"msg_icon":{"value":"5A","color":"04"}},{"paragraph":{"text":"The message paragraph content","blink":"yes","underline":"no","bold":"no","align":"left","color":"00"}},{"paragraph":{"text":"Paragraph 2 message text","blink":"no","underline":"no","bold":"yes","align":"left","color":"02"}}],"reply_options":[{"option_id":"1","reply":{"text":"Accept"}},{"option_id":"2","reply":{"text":"Decline"}}]}}}

example response:

{"msgId":"34","payload":{"amsgId":"82641","ipui":"035edb3a92","msg":{"terminal_msg_status":"fullview"},"sip_id":"1004"}}

Messages flow examples (Location)

as1 (application server 1) -is the user name chosen in chapter 1

service1 - this can be freely defined

Server Application requests HS location using IPUI, DM responds using IPUI in the topic.

as1/service1/ipui/02ea651bab/req/position {"msgId":"as1_77","params":{"hs":"02ea651bab","mode":"dps"}
dm1/02ea651bab/as1/service1/res/position {"msgId":"as1_77","payload":{"location":"location_value"},"status":0}
 
optional notification can be sent after response:
 
dm1/02ea651bab/ipui/02ea651bab/noti/posModule/position {"payload":{"hs":"02ea651bab","location":"location_value"}}

Server Application requests HS location using SIP IDENTIFIER, DM responds using SIP IDENTIFIER in the topic

as1/service1/sip_id/3434/req/position {"msgId":"as1_77","params":{"sip_id":"3434","mode":"dps"}
dm1/3434/as1/service1/res/position {"msgId":"as1_77","payload":{"location":"location_value"},"status":0}
 
optional notification can be sent after response:
 
dm1/3434/sip_id/3434/noti/posModule/position {"payload":{"sip_id":"3434","location":"location_value"}}

Other possibilities. Application server sends request as above but responses are as follows:

as1/service1/ipui/02ea651bab/req/position {"msgId":"as1_77","params":{"hs":"02ea651bab","mode":"dps"}
dm1/posModule/as1/service1/res/position {"msgId":"as1_77","payload":{"hs":"02ea651bab","location":"location_value"},"status":0}
as1/service1/sip_id/3434/req/position {"msgId":"as1_77","params":{"sip_id":"3434","mode":"dps"}
dm1/posModule/as1/service1/res/position {"msgId":"as1_77","payload":{"sip_id":"3434","location":"location_value"},"status":0}
as1/service1/ipui/02ea651bab/req/position {"msgId":"as1_77","params":{"hs":"02ea651bab","mode":"dps"}
hs/02ea651bab/as1/service1/res/position {"msgId":"as1_77","payload":{"location":"location_value"},"status":0}
as1/service1/sip_id/3434/req/position {"msgId":"as1_77","params":{"sip_id":"3434","mode":"dps"}
sip_id/3434/as1/service1/res/position {"msgId":"as1_77","payload":{"location":"location_value"},"status":0}

Location details - subscription, publishing, notifications

SUBSCRIPTIONS: External server (here application server as1) subscribes to the broker for chosen topics, few examples below:


listen to all messages sent to the application server from anyone 

+/+/as1/#

listen to all responses from particular module/service, here "posModule" from any device:

+/posModule/as1/#

listen to all responses from "posModule" from chosen DM:

dm1/posModule/as1/#

listen to all responses from "posModule" from any DM but only regarding HS location

+/posModule/as1/service1/res/position

example response:

dm1/posModule/as1/service1/res/position {"msgId":"posMod_2","payload":{"hs":"02ea651bab","location":"location_value"},"status":0}

listen to all responses from any HS (based on IPUI) regarding location, omitting the module (alternative to previous one)

hs/+/as1/service1/res/position

example response, IPUI can be taken from the topic:

hs/02ea651bab/as1/service1/res/position {"msgId":"posMod_2","payload":{"location":"location_value"},"status":0}

listen to all responses from any HS (based on sip user name) regarding location, omitting the module (alternative to previous one)

sip_id/+/as1/service1/res/position

example response, sip user identifier can be taken from the topic:

sip_id/3434/as1/service1/res/position {"msgId":"posMod_2","payload":{"location":"location_value"},"status":0}


PUBLISHING: Server requests location for particular HS:

publishes message using HS ipui:

topic: "as1/service1/ipui/02ea651bab/req/position"
message: {"msgId":"dps_2","params":{"mode":"dps"}
or
message: {"msgId":"dps_2","params":{"hs":"02ea651bab","mode":"dps"}

publishes message using sip user name:

topic: "as1/service1/sip_id/3434/req/position"
message: {"msgId":"posMod_2","params":{"mode":"dps"}
or
message: {"msgId":"posMod_2","params":{"sip_id":"3434","mode":"dps"}


NOTIFICATIONS: Our system can send additionally notification after the response - in case other devices/modules interested. Topic examples:

Name of the DM and IPUI  is a part of topic

dm1/02ea651bab/ipui/02ea651bab/noti/posModule/position

Name of the DM and sip user identifier is a part of topic

dm1/3434/hs/3434/noti/posModule/position

Handset in/out of charger example


Server needs to activate the handset in/out of charger notification

{"msgId": "hs_status_1004","params": {"sip_id":"1004","hs_status":{"power_status":"on"}}}

example response:

{"msgId":"hs_status_47102","payload":{"power_status":{"battery_level":"64","charger":"off"},"sip_id":"1004"}}

Ready status and Last Will message

External clients could follow our internal rule regarding publishing ready message with status true/false every time when they connect/disconnect.

  1. Ready with true is usually sent when particular module has initiated all needed data / structures and it is ready to work.  - Here client is responsible to publish proper message.
  2. Ready with false will be sent by broker on behalf of the client - This needs to be set before client will connect to the broker using mosquitto API for setting last will like mosquitto_will_set.

    According to the MQTT 3.1.1 specification, the broker must distribute the last will message of a client in the following situations:

    a) The broker detects an I/O error or network failure.
    b) The client fails to communicate within the defined Keep Alive period.
    c) The client does not send a DISCONNECT packet before it closes the network connection.
    d) The broker closes the network connection because of a protocol error.

  3. Both messages with status true or false are sent with retain flag set to true. 

  4. Example:

When service1 ready then application server (as1) sends:
as1/service1/system/ready/noti/rpc {"clientId":"as1/service1","status":true}
 
 
and when disconnected unexpectedly (message sent by broker):
as1/service1/system/ready/noti/rpc {"clientId":"as1/service1","status":false}

Additional notes:

A retained message is a normal MQTT message with the retained flag set to true. The broker stores the last retained message and the corresponding QoS for that topic. Each client that subscribes to a topic pattern that matches the topic of the retained message receives the retained message immediately after they subscribe. The broker stores only one retained message per topic.


Quality of Service

A Quality of Service Level (QoS) for the messages. The level (0,1 or 2) determines the guarantee of a message reaching the other end (client or broker). Currently we use QoS = 0, but we need to consider level 1 or 2 in case of messages which come from application server.

There are 3 QoS levels in MQTT:

  • At most once (0)
  • At least once (1)
  • Exactly once (2).
QoS LevelDescriptionUsage
0It guarantees a best effort delivery. A message won’t be acknowledged by the receiver or stored and redelivered by the sender. This is often called “fire and forget” and provides the same guarantee as the underlying TCP protocol.
  • You have a complete or almost stable connection between sender and receiver. A classic use case is when connecting a test client or a front end application to a MQTT broker over a wired connection.
  • You don’t care if one or more messages are lost once a while. That is sometimes the case if the data is not that important or will be sent at short intervals, where it is okay that messages might get lost.
  • You don’t need any message queuing. Messages are only queued for disconnected clients if they have QoS 1 or 2 and a persistent session.
1It is guaranteed that a message will be delivered at least once to the receiver. But the message can also be delivered more than once. The sender will store the message until it gets an acknowledgement from the receiver.
  • You need to get every message and your use case can handle duplicates. The most often used QoS is level 1, because it guarantees the message arrives at least once. Of course your application must be tolerating duplicates and process them accordingly.
  • You can’t bear the overhead of QoS 2. Of course QoS 1 is a lot fast in delivering messages without the guarantee of level 2.
2It guarantees that each message is received only once by the counterpart. It is the safest and also the slowest quality of service level. The guarantee is provided by two flows there and back between sender and receiver.
  • It is critical to your application to receive all messages exactly once. This is often the case if a duplicate delivery would do harm to application users or subscribing clients. You should be aware of the overhead and that it takes a bit longer to complete the QoS 2 flow.


Important !

Messages may be sent at any QoS level, and clients may attempt to subscribe to topics at any QoS level. This means that the client chooses the maximum QoS it will receive. For example, if a message is published at QoS 2 and a client is subscribed with QoS 0, the message will be delivered to that client with QoS 0. If a second client is also subscribed to the same topic, but with QoS 2, then it will receive the same message but with QoS 2. For a second example, if a client is subscribed with QoS 2 and a message is published on QoS 0, the client will receive it on QoS 0.

Higher levels of QoS are more reliable, but involve higher latency and have higher bandwidth requirements.

Additional notes:

  1. All messages sent with QoS 1 and 2 will also be queued for offline clients, until they are available again. But queuing is only happening, if the client has a persistent session.