Skip to content

Proposal: MQTT event handler

Jump to bottom
Ola Palm edited this page Apr 3, 2020 · 16 revisions

Todo:

  • Add event class: register, core, call

This is a discussion page for discussing the new MQTT event module. Currently (Nov 29 2017) it's in a development branch called "mqtt_module". In this discussion we separate events emitted by baresip from API actions (request/response). This document focuses on the events.

Identifiers

Events are identified by

  • SIP Account
  • SIP Call-ID header value

Not all events have a Call-ID.

Event types

All events have a "type" field

Currently the uag_event_str from ua.c is used:

  •     `case UA_EVENT_REGISTERING:          return "REGISTERING";`

  •     `case UA_EVENT_REGISTER_OK:          return "REGISTER_OK";`

  •     `case UA_EVENT_REGISTER_FAIL:        return "REGISTER_FAIL";`

  •     `case UA_EVENT_UNREGISTERING:        return "UNREGISTERING";`

  •     `case UA_EVENT_SHUTDOWN:             return "SHUTDOWN";`

  •     `case UA_EVENT_EXIT:                 return "EXIT";`

  •     `case UA_EVENT_CALL_INCOMING:        return "CALL_INCOMING";`

  •     `case UA_EVENT_CALL_RINGING:         return "CALL_RINGING";`

  •     `case UA_EVENT_CALL_PROGRESS:        return "CALL_PROGRESS";`

  •     `case UA_EVENT_CALL_ESTABLISHED:     return "CALL_ESTABLISHED";`

  •     `case UA_EVENT_CALL_CLOSED:          return "CALL_CLOSED";`

  •     `case UA_EVENT_CALL_TRANSFER_FAILED: return "TRANSFER_FAILED";`

  •     `case UA_EVENT_CALL_DTMF_START:      return "CALL_DTMF_START";`

  •     `case UA_EVENT_CALL_DTMF_END:        return "CALL_DTMF_END";`

Format

Currently the format for a message is simple. AOR and event in a string separated by a comma.

sip:aeh@iptel.org,CALL_ESTABLISHED

We would like to suggest a JSON format instead. Example:

{
    "type" :       "CALL_ESTABLISHED",
    "accountaor" : "sip:alice@biloxi.example.com",
    "direction" :  "incoming",
    "peeruri" :    "sip:bob@sollentuna.example.com",
    "peername" :   "Bob STHLM"
}

The type and accountaor exists today. If possible, some metadata about the event can be added, like the above "direction" and "peeraor". This may be added in the future.

Peername is not always known, and if not present the field will not be present.

Topics

Topics should be configurable. For events, the should be an option to send events on a specific channel per type. This is to be able to have filtering in subscriptions of events on the monitoring system (the consumer of the MQTT messages).

Event Base topic

The base topic for events should be configurable. If no other topic-related configuration options are available, this is the topic used for publishing events.

mqtteventbasetopic = "/baresip/events"

Account in topic

mqtteventaddaor = yes | no

If enabled, the AOR is added after the base topic, if the event is related to an AOR. The SHUTDOWN event is an example of a generic event that is not related to an AOR, and therefore no AOR will be added.

Considering this configuration:

mqtteventbasetopic = "/edvina/baresip/events"

mqtteventaddaor = yes

The event will be published on

/edvina/baresip/events/sip:oej@edvina.net

Note: If MQTT is bridged to AMQP (Rabbit MQ) the dots in a topic is going to create problems.

Event type for topic

mqtteventaddtype = yes | no

If enabled, the event type in lower case is added to the topic

/baresip/events/call_incoming

will be the topic for incoming calls. The event type is added BEFORE the AOR if mqtteventaddaor is enabled. Consider this configuration:

mqtteventbasetopic = "/edvina/baresip/events"

mqtteventaddaor = yes

mqtteventaddtype = yes

An event will be published on the following topic:

/edvina/baresip/events/call_progress/sip:oej@edvina.net

But an event with no relationship to an AOR will be published on a different topic without an AOR

/edvina/baresip/events/shutdown

Subscription examples

Subscriptions can be set up for all events on the following topic

/baresip/events/#

If all events to a particular event is needed, regardless of AOR

/baresip/events/call_incoming/#

If all events related to a particular AOR is what one is looking for

/baresip/events/+/sip:ola@palm.example.com

Sample messages

{
   "type":"REGISTER_OK",
   "accountaor":"sip:user@domain.com",
   "param":"200 OK"
}
{  
   "type":"CALL_ESTABLISHED",
   "accountaor":"sip:user@domain.com",
   "direction":"outgoing",
   "peeruri":"sip:echo@domain.com",
   "peername" : "Nisse @ Home",
   "param":"sip:echo@domain.com"
}
{  
   "type":"CALL_RTCP",
   "accountaor":"sip:user@domain.com",
   "direction":"outgoing",
   "peeruri":"sip:echo@domain.com",
   "peername" : "Iris",
   "param":"audio",
   "rtcp_stats":{  
      "tx":{  
         "sent":497,
         "lost":5,
         "jit":3250
      },
      "rx":{  
         "sent":474,
         "lost":15,
         "jit":3750
      },
      "rtt":17213
   }
}
Clone this wiki locally