Difference between revisions of "Homebrew repeater protocol"

(→‎Disclaimer)
 
 
(12 intermediate revisions by 2 users not shown)
Line 4: Line 4:
  
 
== Disclaimer ==
 
== Disclaimer ==
−
This protocol should only be used for connecting repeaters/hotspots directly. To connect networks, other protocols exist - please contact the dev team so that a good implementation can be made. We can't give support if the protocol is used for other things than connecting repeaters/hotspots directly.
+
Connecting to Brandmeister with the Homebrew and MMDVM Host protocols is reserved for repeaters and hotspots with an onboard radio (RF) module.  
 +
 
 +
If you are writing software or building an appliance to connect to Brandmeister without a radio transmitter, you must use a more suitable protocol. Please contact the development team (https://t.me/BRANDMEISTERGENERALSUPPORT) and we will assist you in choosing the best protocol for your application.
 +
 
 +
If you want to interconnect another amateur radio network with BrandMeister, you must use the [[Open Bridge]] protocol. Please post a request on the Brandmeister support platform (https://support.brandmeister.network) for assistance.
 +
 
 +
If you want to interconnect a non-amateur radio network to BrandMeister, don't.
 +
 
 +
Do not create software solutions or build appliances without onboard radio modules that impersonate the HomeBrew or MMDVM Host protocols. This configuration might not work with newer versions of BrandMeister and we cannot provide any support for it.
  
 
== G4KLX MMDVMHost version ==
 
== G4KLX MMDVMHost version ==
Line 49: Line 57:
 
** :1 is slot number (:0 for DMO channel, :1 and :2 for Slot 1 and Slot 2),
 
** :1 is slot number (:0 for DMO channel, :1 and :2 for Slot 1 and Slot 2),
 
* There is no acknowledge message.
 
* There is no acknowledge message.
−
 
−
=== Cloud Messaging extension (push notifications) ===
 
−
 
−
One of the targets of the Homebrew Protocol is mobile devices such as mobile phones. This kind of devices have very strong requirements for power saving ([http://www.drdobbs.com/mobile/power-management-for-mobile-devices/184407880 Power Management for Mobile Devices]). To make access for these devices more comfortable we added support of a native activation mechanism to Homebrew Protocol. Now we can activate devices via Google's [https://firebase.google.com/docs/cloud-messaging/ Firebase Cloud Messaging] which is a native mechanism for Android devices.
 
−
 
−
==== Managing connection state ====
 
−
 
−
To do this, the BrandMeister DMR Server supports the following new messages that may be sent by the client:
 
−
 
−
* Switch connection state to idle. In the idle state the server stops sending any messages to the client via UDP (keep-alive messages are not required).
 
−
** Message format: <pre>RPTIDLE01234567-393838907279:bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...</pre> Where 01234567 is the repeater ID (hexadecimal string of 8 characters) then application token ID (393838907279), deimeter (":") and the last part is the device token. We recommend to send this message several times (i.e. 3 times), and the server will respond with MSTACK
 
−
* Switch connection state back to active.<br>
 
−
** Message format: <pre>RPTWAKE01234567-393838907279:bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...</pre> Where 01234567 is the repeater ID (hexadecimal string of 8 characters) then application token ID (393838907279), deimeter (":") and the last part is the device token. Upon success the server will respond with MSTACK.
 
−
 
−
==== Downstream message ====
 
−
 
−
In the connection's idle state the server will send any data such as the headers of any voice calls, data calls, and CSBK (but not voice frames) via Cloud Messaging. Client applications should then go back and switch the connection to an active state to get a stream over UDP.
 
−
 
−
<pre>
 
−
{
 
−
  "data" :
 
−
  {
 
−
    "type" : "Homebrew Repeater",
 
−
    "data" : "010203040506070809..."
 
−
  },
 
−
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
 
−
}
 
−
</pre>
 
−
 
−
'''data/data''' field contains normal DMRD message of Homebrew Protocol in hexadecimal representation.
 
−
 
−
==== Application IDs and keys ====
 
−
 
−
We strongly recommended to use your own application token ID. In that case please provide us your application token ID and authorisation key. Both will be hardcoded in the source code. Default application token ID is <font size="+1">393838907279</font>
 
−
 
−
== Proposal for extensions on version 2.0 ==
 
−
 
−
The main reason for this extension is support of homebrew terminal mode that should have different client UX and behaviour on the server side.
 
−
 
−
=== Configure terminal mode ===
 
−
 
−
'''The message should be sent instead of repeater Configuration protocol message immediately after authentication'''.<br/>
 
−
Request of client:
 
−
<pre>TRMENT01234567:callsign:software-version</pre>
 
−
Response of server:
 
−
<pre>TRMACK01234567</pre>
 
−
''01234567'' is a hexadecimal ID of client<br/>
 
−
''callsign'' is a text string of user callsign<br/>
 
−
''software-version'' is a string to identify software and it's version
 
−
 
−
=== Subscribe group ===
 
−
Request of client:
 
−
<pre>TRMSUB01234567:TG4321</pre>
 
−
Response of server:
 
−
<pre>TRMACK01234567</pre>
 
−
01234567 is a hexadecimal ID of client<br/>
 
−
TG4321 is a group ID
 
−
 
−
=== Unsubscribe group ===
 
−
Request of client:
 
−
<pre>TRMUNS01234567:TG4321</pre>
 
−
Response of server:
 
−
<pre>TRMACK01234567</pre>
 
−
01234567 is a hexadecimal ID of client<br/>
 
−
TG4321 is a group ID
 
−
 
−
=== Unsubscribe all groups ===
 
−
Request of client:
 
−
<pre>TRMUNS01234567:ALL</pre>
 
−
Response of server:
 
−
<pre>TRMACK01234567</pre>
 
−
01234567 is a hexadecimal ID of client
 
−
 
−
=== Enter exclusive mode ===
 
−
Request of client:
 
−
<pre>TRMEXL01234567:TG4321</pre>
 
−
Response of server:
 
−
<pre>TRMACK01234567</pre>
 
−
01234567 is a hexadecimal ID of client<br/>
 
−
TG4321 is a group ID (PV1234567 is a private ID)
 
−
 
−
=== Exit exclusive mode ===
 
−
Request of client:
 
−
<pre>TRMEXL01234567:EXIT</pre>
 
−
Response of server:
 
−
<pre>TRMACK01234567</pre>
 
−
01234567 is a hexadecimal ID of client
 
−
 
−
=== DMR Data ===
 
−
Slot flag should be unset.
 
  
  

Latest revision as of 13:11, 10 April 2023

At the moment we have two versions of the Homebrew repeater protocol:

  • A version that is specified by DL5DI as the result of discussion between DL5DI, G4KLX and DG1HT
  • A version that is implemented by G4KLX with his MMDVMHost software

Disclaimer

Connecting to Brandmeister with the Homebrew and MMDVM Host protocols is reserved for repeaters and hotspots with an onboard radio (RF) module.

If you are writing software or building an appliance to connect to Brandmeister without a radio transmitter, you must use a more suitable protocol. Please contact the development team (https://t.me/BRANDMEISTERGENERALSUPPORT) and we will assist you in choosing the best protocol for your application.

If you want to interconnect another amateur radio network with BrandMeister, you must use the Open Bridge protocol. Please post a request on the Brandmeister support platform (https://support.brandmeister.network) for assistance.

If you want to interconnect a non-amateur radio network to BrandMeister, don't.

Do not create software solutions or build appliances without onboard radio modules that impersonate the HomeBrew or MMDVM Host protocols. This configuration might not work with newer versions of BrandMeister and we cannot provide any support for it.

G4KLX MMDVMHost version

This version of the homebrew repeater protocol is implemented at BrandMeister as "MMDVM Host". The protocol is very close to a version of DL5DI but has some principal changes that are not documented in that specification. Over time, changes introduced have alienated these two protocols.

https://github.com/g4klx/MMDVMHost g4klx/MMDVMHost

Publicly-available version as initially specified by DL5DI

You can find the spec here: File:DMRplus IPSC Protocol for HB repeater.pdf This version of the homebrew repeater protocol is implemented at BrandMeister as "Homebrew Repeater"

Please note, this specification is not necessarily complete.

Corrections and additions

  • Default UDP port is 62030.
  • All messages except DMRD are in text form.
  • Repeater ID should be presented as a hexadecimal string of 8 characters in length (except DMRD, which is binary).
  • Salt and SHA-256 hash of the authentication protocol should be also presented as hexadecimal strings.
  • Use salt value as a string when calculating hash value (see attached PHP example code).
  • Configuration protocol has 306 bytes in length.
  • Interval of PING messages should be in the range 5 - 15 seconds (5 is preferred for most firewalls).
  • When the TX and RX frequencies have same value we consider this case as a connected hotspot in DMO mode.
  • In case of DMO hotspot or IP client all DMR traffic should be transmitted with unset bit of selected slot.

Site Beacon and RSSI (extensions)

  • Synchronous Site Beacon is very important for passive automatic roaming. We added a special message to the protocol. It should be sent by the server to repeaters. No response is required.
    • Message format: 
      RPTSBKN01234567
      Where 01234567 is ID of repeater (hexadecimal string of 8 characters).
  • BrandMeister supports handling of RSSI reports:
    • Message format: 
      RPTRSSI01234567:1-120.0
      Where
      • 01234567 is ID of repeater (hexadecimal string of 8 characters),
      •  :1 is slot number (:0 for DMO channel, :1 and :2 for Slot 1 and Slot 2),
      • -120.0 is RSSI value in dBm.
    • There is no acknowledge message.

Incoming call interrupt

Client could request server to interrupt current incoming call.

  • Message format: 
    RPTINTR01234567:1
    Where
    • 01234567 is ID of repeater (hexadecimal string of 8 characters),
    •  :1 is slot number (:0 for DMO channel, :1 and :2 for Slot 1 and Slot 2),
  • There is no acknowledge message.


Examples

PHP

Retrieved from "https://wiki.brandmeister.network/index.php?title=Homebrew_repeater_protocol&oldid=18983"

At the moment we have two versions of the Homebrew repeater protocol:

Disclaimer[edit]

This protocol should only be used for connecting repeaters/hotspots directly. To connect networks, other protocols exist - please contact the dev team so that a good implementation can be made. We can't give support if the protocol is used for other things than connecting repeaters/hotspots directly.

G4KLX MMDVMHost version[edit]

This version of the homebrew repeater protocol is implemented at BrandMeister as "MMDVM Host". The protocol is very close to a version of DL5DI but has some principal changes that are not documented in that specification. Over time, changes introduced have alienated these two protocols.

https://github.com/g4klx/MMDVMHost g4klx/MMDVMHost

Publicly-available version as initially specified by DL5DI[edit]

You can find the spec here: File:DMRplus IPSC Protocol for HB repeater.pdf This version of the homebrew repeater protocol is implemented at BrandMeister as "Homebrew Repeater"

Please note, this specification is not necessarily complete.

Corrections and additions[edit]

Site Beacon and RSSI (extensions)[edit]

Incoming call interrupt[edit]

Client could request server to interrupt current incoming call.

Cloud Messaging extension (push notifications)[edit]

One of the targets of the Homebrew Protocol is mobile devices such as mobile phones. This kind of devices have very strong requirements for power saving (Power Management for Mobile Devices). To make access for these devices more comfortable we added support of a native activation mechanism to Homebrew Protocol. Now we can activate devices via Google's Firebase Cloud Messaging which is a native mechanism for Android devices.

Managing connection state[edit]

To do this, the BrandMeister DMR Server supports the following new messages that may be sent by the client:

Downstream message[edit]

In the connection's idle state the server will send any data such as the headers of any voice calls, data calls, and CSBK (but not voice frames) via Cloud Messaging. Client applications should then go back and switch the connection to an active state to get a stream over UDP. 

{
  "data" :
   {
     "type" : "Homebrew Repeater",
     "data" : "010203040506070809..."
   },
   "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}

data/data field contains normal DMRD message of Homebrew Protocol in hexadecimal representation.

Application IDs and keys[edit]

We strongly recommended to use your own application token ID. In that case please provide us your application token ID and authorisation key. Both will be hardcoded in the source code. Default application token ID is 393838907279

Proposal for extensions on version 2.0[edit]

The main reason for this extension is support of homebrew terminal mode that should have different client UX and behaviour on the server side.

Configure terminal mode[edit]

The message should be sent instead of repeater Configuration protocol message immediately after authentication.
Request of client: 

TRMENT01234567:callsign:software-version

Response of server: 

TRMACK01234567

01234567 is a hexadecimal ID of client
callsign is a text string of user callsign
software-version is a string to identify software and it's version

Subscribe group[edit]

Request of client: 

TRMSUB01234567:TG4321

Response of server: 

TRMACK01234567

01234567 is a hexadecimal ID of client
TG4321 is a group ID

Unsubscribe group[edit]

Request of client: 

TRMUNS01234567:TG4321

Response of server: 

TRMACK01234567

01234567 is a hexadecimal ID of client
TG4321 is a group ID

Unsubscribe all groups[edit]

Request of client: 

TRMUNS01234567:ALL

Response of server: 

TRMACK01234567

01234567 is a hexadecimal ID of client

Enter exclusive mode[edit]

Request of client: 

TRMEXL01234567:TG4321

Response of server: 

TRMACK01234567

01234567 is a hexadecimal ID of client
TG4321 is a group ID (PV1234567 is a private ID)

Exit exclusive mode[edit]

Request of client: 

TRMEXL01234567:EXIT

Response of server: 

TRMACK01234567

01234567 is a hexadecimal ID of client

DMR Data[edit]

Slot flag should be unset.


Examples[edit]

PHP