Simple External Application is a new interface of BrandMeister DMR Server. This link provides simple access for external audio applications such as network bridges or interactive voice applications. "Simple" means developer should not care about interleaving, locks and other stuff. Just plain voice header and AMBE frames of L3. One call simultaneously per connection.

This is incomplete version of specification!


Rewind Protocol

Rewind is our under-layer protocol required for communication with BrandMeister DMR Server. It is based on UDP. Byte-order is LE.

Note: there are two sequence counters. One for routine messages and another one for real-time data (from REWIND_TYPE_DMR_DATA_BASE to REWIND_TYPE_DMR_AUDIO_FRAME). For real-time data you also should set flag REWIND_FLAG_REAL_TIME_1.

Protocol definition header is now available here

Messages for External Application

Link establishment

REWIND_TYPE_KEEP_ALIVE

Keep-alive messages should be sent by client every 5 seconds. struct RewindVersionData should follow after Rewind header.

  • number - ID of application, should be allocated by administrators of BrandMeister
  • service - should be set to REWIND_SERVICE_SIMPLE_APPLICATION
  • version - UTF-8 encoded message contains application name and version

Server respond to this message with the same type but without content (just header).

REWIND_TYPE_CLOSE

Simple message to close connection, has no parameters and confirmations.

REWIND_TYPE_CHALLENGE

There is no special login message, new connection should be established by REWIND_TYPE_KEEP_ALIVE. REWIND_TYPE_CHALLENGE will be send by BrandMeister Server when it detects new connection. The parameter of this message is salt value (please check example bellow).

REWIND_TYPE_AUTHENTICATION

This message is result of processing message REWIND_TYPE_CHALLENGE by client. The parameter is value of calculation SHA256 hash function (please check example bellow). A result of successful authentication procedure will be empty message REWIND_TYPE_KEEP_ALIVE.

Operational support

REWIND_TYPE_REPORT

Some kind of debugging extension. This message will be send by BrandMeister Server. Parameter of message is UTF-8 encoded text (please check example bellow).

Call control and subscription management

REWIND_TYPE_BUSY_NOTICE

Use this message to drop incoming call from the server. Message has no content.

REWIND_TYPE_CONFIGURATION

Using this message you can configure options of connection. struct RewindConfigurationData

  • options - set of bits:
    • REWIND_OPTION_SUPER_HEADER - with this option BrandMeister Server will send REWIND_TYPE_SUPER_HEADER

On success BrandMeister Server will respond with REWIND_TYPE_CONFIGURATION without content.

REWIND_TYPE_SUBSCRIPTION

To simplify the process of administration and reduce amount of administrative work an application could make subscription to DMR data by itself immediately after authentication procedure. struct RewindSubscriptionData should follow after Rewind header.

  • type - set to 7 for group voice call
  • number - ID of talking group

On success BrandMeister Server will respond with REWIND_TYPE_SUBSCRIPTION without content.

You can make several subscriptions for connection. Subscription procedure is optional, all routing stuff can be done by LUA on the server side.

REWIND_TYPE_CANCELLING

This message cancels subscriptions created by REWIND_TYPE_SUBSCRIPTION.

This message has two options:

  • To cancel all active subscriptions - the message has no content.
  • To cancel particular subscription - use the same syntax as REWIND_TYPE_SUBSCRIPTION

On success BrandMeister Server will respond with REWIND_TYPE_CANCELLING without content.

REWIND_TYPE_SESSION_POLL

This message allows to check actice call sessions. You have to pass `struct RewindSessionPollData`:

  • type - set to 8 to check source ID or 9 to check destination ID
  • flag - set to 7 for group voice call (only when type is 9)
  • number - ID
  • state - should be 0

You will get the same structure as a response. Field state will have 0 if there no active calls or 1 if there an active call.

Call transmission

REWIND_TYPE_DMR_DATA_BASE

This is a base number for group of messages:

  • REWIND_TYPE_DMR_DATA_BASE + 1 is Voice Header (Full LC).
    This is normal structure of DMR Voice Header, 12 bytes in length (ETSI TS 102 361-1). You can skip calculation of CRC.
  • REWIND_TYPE_DMR_DATA_BASE + 2 is transmission terminator. No content required or sent.

Both messages may be sent several times at once (2-3 times with same sequence number) to be sure on successful delivery.

REWIND_TYPE_DMR_AUDIO_FRAME

This message should contain triple AMBE frames of mode 33. Each of 9 bytes, 27 bytes total.

REWIND_TYPE_DMR_EMBEDDED_DATA

This message contains value of LC (10 bytes), which can be transferred via embedded signalling during voice call. Suitable to transfer Talker Alias and in-call GPS.

REWIND_TYPE_SUPER_HEADER

Incoming call from BrandMeister

You will get struct RewindSuperHeader in parallel with normal DMR header (REWIND_TYPE_DMR_DATA_BASE + 1)
This header offloads External Application from database lookups to get callsigns of callee and caller.

Note: BrandMeister Server will send these messges only if client configured its sending with REWIND_TYPE_CONFIGURATION.

Outgoing call from Application

External Application can send struct RewindSuperHeader instead of normal DMR header to start the call.
You call pass callsigns at the fields sourceCall and/or destinationCall (and 0 at corresponding ID field) to make BrandMeister lookup right ID. Talker Alias will be automatically set to sourceCall it is defined.

REWIND_TYPE_FAILURE_CODE

This message will be sent by BrandMeister server in case when sourceCall or destinationCall could not be resolved during processing REWIND_TYPE_SUPER_HEADER. This message will contain text of failure like it is on REWIND_TYPE_REPORT

Client Library and Example applications

Our DigestPlay is supplied with client library that implements transport layer and login procedure.

DigestPlay written in C

Call recorder written in Go

Simple External Application is a new interface of BrandMeister DMR Server. This link provides simple access for external audio applications such as network bridges or interactive voice applications. "Simple" means developer should not care about interleaving, locks and other stuff. Just plain voice header and AMBE frames of L3. One call simultaneously per connection.

This is incomplete version of specification!


Rewind Protocol[edit]

Rewind is our under-layer protocol required for communication with BrandMeister DMR Server. It is based on UDP. Byte-order is LE.

Note: there are two sequence counters. One for routine messages and another one for real-time data (from REWIND_TYPE_DMR_DATA_BASE to REWIND_TYPE_DMR_AUDIO_FRAME). For real-time data you also should set flag REWIND_FLAG_REAL_TIME_1.

Protocol definition header is now available here

Messages for External Application[edit]

Link establishment[edit]

REWIND_TYPE_KEEP_ALIVE[edit]

Keep-alive messages should be sent by client every 5 seconds. struct RewindVersionData should follow after Rewind header.

Server respond to this message with the same type but without content (just header).

REWIND_TYPE_CLOSE[edit]

Simple message to close connection, has no parameters and confirmations.

REWIND_TYPE_CHALLENGE[edit]

There is no special login message, new connection should be established by REWIND_TYPE_KEEP_ALIVE. REWIND_TYPE_CHALLENGE will be send by BrandMeister Server when it detects new connection. The parameter of this message is salt value (please check example bellow).

REWIND_TYPE_AUTHENTICATION[edit]

This message is result of processing message REWIND_TYPE_CHALLENGE by client. The parameter is value of calculation SHA256 hash function (please check example bellow). A result of successful authentication procedure will be empty message REWIND_TYPE_KEEP_ALIVE.

Operational support[edit]

REWIND_TYPE_REPORT[edit]

Some kind of debugging extension. This message will be send by BrandMeister Server. Parameter of message is UTF-8 encoded text (please check example bellow).

Call control and subscription management[edit]

REWIND_TYPE_BUSY_NOTICE[edit]

Use this message to drop incoming call from the server. Message has no content.

REWIND_TYPE_CONFIGURATION[edit]

Using this message you can configure options of connection. struct RewindConfigurationData

On success BrandMeister Server will respond with REWIND_TYPE_CONFIGURATION without content.

REWIND_TYPE_SUBSCRIPTION[edit]

To simplify the process of administration and reduce amount of administrative work an application could make subscription to DMR data by itself immediately after authentication procedure. struct RewindSubscriptionData should follow after Rewind header.

On success BrandMeister Server will respond with REWIND_TYPE_SUBSCRIPTION without content.

You can make several subscriptions for connection. Subscription procedure is optional, all routing stuff can be done by LUA on the server side.

REWIND_TYPE_CANCELLING[edit]

This message cancels subscriptions created by REWIND_TYPE_SUBSCRIPTION.

This message has two options:

On success BrandMeister Server will respond with REWIND_TYPE_CANCELLING without content.

REWIND_TYPE_SESSION_POLL[edit]

This message allows to check actice call sessions. You have to pass `struct RewindSessionPollData`:

You will get the same structure as a response. Field state will have 0 if there no active calls or 1 if there an active call.

Call transmission[edit]

REWIND_TYPE_DMR_DATA_BASE[edit]

This is a base number for group of messages:

Both messages may be sent several times at once (2-3 times with same sequence number) to be sure on successful delivery.

REWIND_TYPE_DMR_AUDIO_FRAME[edit]

This message should contain triple AMBE frames of mode 33. Each of 9 bytes, 27 bytes total.

REWIND_TYPE_DMR_EMBEDDED_DATA[edit]

This message contains value of LC (10 bytes), which can be transferred via embedded signalling during voice call. Suitable to transfer Talker Alias and in-call GPS.

REWIND_TYPE_SUPER_HEADER[edit]

Incoming call from BrandMeister[edit]

You will get struct RewindSuperHeader in parallel with normal DMR header (REWIND_TYPE_DMR_DATA_BASE + 1)
This header offloads External Application from database lookups to get callsigns of callee and caller.

Note: BrandMeister Server will send these messges only if client configured its sending with REWIND_TYPE_CONFIGURATION.

Outgoing call from Application[edit]

External Application can send struct RewindSuperHeader instead of normal DMR header to start the call.
You call pass callsigns at the fields sourceCall and/or destinationCall (and 0 at corresponding ID field) to make BrandMeister lookup right ID. Talker Alias will be automatically set to sourceCall it is defined.

REWIND_TYPE_FAILURE_CODE[edit]

This message will be sent by BrandMeister server in case when sourceCall or destinationCall could not be resolved during processing REWIND_TYPE_SUPER_HEADER. This message will contain text of failure like it is on REWIND_TYPE_REPORT

Client Library and Example applications[edit]

Our DigestPlay is supplied with client library that implements transport layer and login procedure.

DigestPlay written in C

Call recorder written in Go