Difference between revisions of "Homebrew repeater protocol/Spec"

Latest revision as of 23:16, 26 December 2015 (view source) Pd0zry (Talk | contribs) (→‎Keep-Alive)

(No difference)

---

Latest revision as of 23:16, 26 December 2015

Revision History

Date	Description
2015/07/02	DL5DI Initial version based on specifications from Jonathan Naylor G4KLX for the repeater side added requirements from Torsten Schultze DG1HT and Hans-J. Barthen DL5DI for the network/reflector side
2015/07/08	Changes implemented after first review by G4KLX Rptr-ID added to all protocols Examples integrated
2015/07/09	ColorCode added to configuration protocol
2015/07/26	Modifications on sample values Order of 16/32 bit values specified as like “on air / ETSI” format
2015/12/24	Added sequence graphs

Login

<mscgen caption="Login Sequence" uniquifier="Login"> msc {

 Host, Master;
 Host->Master [label="RPTL00040178"];
 --- [label="Deny"];
 Master->Host [label="MSTNAK00040178"];
 --- [label="Accept"];
 Master->Host [label="MSTACK000401780A7ED498"];

} </mscgen> The repeater connects to the master by issuing the seven byte RPTL command below:

'R' 'P' 'T' 'L' followed by the repeater id as a four byte binary integer.

Example:

RPTL00040178

The master replies with either MSTNAK if the repeater id is not recognized or some other reason not

to allow the repeater to log in, or a MSTACK if authentication can begin, these are detailed below:

'M' 'S' 'T' 'N' 'A' 'K' followed by the repeater id as a four byte binary integer.

Example:

MSTNAK00040178

'M' 'S' 'T' 'A' 'C' 'K' followed by the repeater id as a four byte binary integer

and a random 32-bit integer.

Example:

MSTACK000401780A7ED498

This 32-bit integer is prepended to a secret pass phrase issued by the person running the master and is in effect the password for system entry for this repeater.

The 32-bit integer should be interpreted as a 32-bit pattern and not as an integer and used as-is. This new passphrase is then subject to SHA-256 and the reply sent to the master: 'R' 'P' 'T' 'K' followed by the repeater id as a four byte binary integer and by the SHA-256 output.

Example: (with a passphrase “DL5DI” and the random number from the example above the SHA-256 is built from “0A7ED498DL5DI”)

RPTK00040178cbf0e29abbd11c6573825d36a664e3064441f91fc815ac5dc5ca570d4c4a5f85

If all is well then the master will reply with MSTACK if the login was successful or an MSTNAK is the login was rejected. These are shown below: 'M' 'S' 'T' 'A’ 'C' 'K' followed by the repeater id as a four byte binary integer.

Example:

MSTACK00040178

'M' 'S' 'T' 'N' 'A' 'K' followed by the repeater id as a four byte binary integer.

Example:

MSTNAK00040178

Keep-Alive

<mscgen caption="Keep-alive Sequence" uniquifier="KeepAlive"> msc {

 Host, Master;
 Master=>Host [label="MSTPING00040178"];
 Host=>Master [label="RPTPONG00040178"];
 ...;
 --- [label="No pong received retry"];
 Master=>Host [label="MSTPING00040178"];
 Host=>Master [label="RPTPONG00040178"];
 ...;
 --- [label="Close connection master side"];
 Master=>Host [label="MSTCL00040178"];
 ...;
 --- [label="Close connection repeater side"];
 Host=>Master [label="RPTCL00040178"];

} </mscgen>

Every minute a ping message will be sent by the repeater to the master and it will expect a reply from the master. If no reply is received from the master within a certain period, the repeater will try another ping and await a pong. This will occur a number of times spaced one minute apart.

If no ping is received the master will mark the link as dead. Any later packets from the repeater are met with MSTNAK replies and the repeater should log into the master again.

These are: 'M' 'S' 'T' 'P' 'I' 'N' 'G' followed by the repeater id as a four byte binary integer.

Example:

MSTPING00040178

'R' 'P' 'T' 'P' 'O' 'N' 'G' followed by the repeater id as a four byte binary integer.

Example:

RPTPONG00040178

If the master is closing down then it should send a MSTCL to all of the attached repeaters and if a repeater is closing down it should send an RPTCL to the master.

These are: 'M' 'S' 'T' 'C' 'L' followed by the repeater id as a four byte binary integer.

Example:

MSTCL00040178

'R' 'P' 'T' 'C' 'L' followed by the repeater id as a four byte binary integer.

Example:

RPTCL00040178

Configuration

After logging in, the repeater will send a packet detailing it's configuration to the master. All fields have a fix length, all 16/32bit hex values have the order like on air (ETSI spec). The packet format is:

Name	Length	Values	Meaning/Comment
Signature	4 Byte	'R' 'P' 'T' 'C' in ASCII
Callsign	8 Byte ASCII	DL5DI___	The allocated callsign of the repeater, Filled up with spaces
RptrId	4 Byte Hex	00000000-FFFFFFFF	3 Bytes registered DMR-ID for public repeaters, 4 Bytes for private repeaters
RX Freq	9 Digit	434787500	The receive frequency decimal in Hertz.
TX Freq	9 Digit	434787500	The transmit frequency decimal in Hertz.
TX Power	2 Digit dec	00-99	The transmit power in dBm, decimal.
ColorCode	2 Digit dec	01-15	The ColorCode/Systemcode of the repeater
Latitude	8 Digit decimal	-90 to +90	Samples: +50.4243 -07.2432 The latitude with North as positive, in ASCII. A decimal point or decimal comma is allowed. (8 Digits including 4 decimals, +/- and decimal delimiter)
Longitude	9 Digit decimal	-180 to +180	Samples: +007.3412 -142.1234 The longitude with East as positive, in ASCII. A decimal point or decimal comma is allowed. (9 Digits including 4 decimals, +/- and decimal delimiter)
Height	3 Digit dec	000-999	The antenna height above ground level in meters
Location	20 Digit		The nominal location of the repeater. This is a free form text field. (only ASCII, no special country specific characters or HTML codes, URLs)
Description	20 Digit		Optional information about the repeater. This is a free form text field. (only ASCII, no special country specific characters or HTML codes, URLs, no advertisements or nonAmateur Radio content)
URL	124 Digit	www.ham-dmr.de	Optional web page for the repeater or group. This is a free form text field. (no advertisements or non-Amateur Radio related links) “http://” not required
Software ID	40 Byte	linux:dmrrepeater-20150702	software-ID with version number (no HTML, no advertising, only identification)
Package ID	40 Byte	rpm:dmrrepeater-20150720-2_i386	Package-ID with version number and platform (no HTML, no advertising, only identification)

When received by the master, it will reply with a 'M' 'S' 'T' 'A’ 'C' 'K' followed by the repeater id as a four byte binary integer.

Example:

MSTACK00040178

Data

All data passing packets have the same format and are 53 bytes in length. The content is:

Name	Length	Values	Meaning/Comment
Signature	4 Bytes ASCII	'D' 'M' 'R' 'D'	This allows multiplexing with other digital audio protocols. Seq No 1 Byte 00-ff (0-255) Starts at zero for each incoming transmission, wraps back to zero when 256 is reached.
Src Id	3 Bytes	000000-FFFFFF	This implies that data cannot be passed until the identity of the transmitter is known.
Dst Id	3 Bytes	000000-FFFFFF	This implies that data cannot be passed until the identity of the destination is known.
RptrId	4 Bytes	00000000-FFFFFFFF	3 Bytes registered DMR-ID for public repeaters, 4 Bytes for private repeaters
Slot No	1 Bit	0b0000000x	0 for slot 1, 1 for slot 2.
Call Type	1 Bit	0b000000x0	0 for group call, 1 for unit to unit.
Frame Type	2 Bit	0b0000xx00	0x00 for voice, 0x01 for voice sync, 0x10 for data sync, 0x11 unused.
Data Type or Voice Seq	4 Bits	0bxxxx0000	When data sync, this is the Data Type from the Slot Type. When voice/voice sync this is the voice sequence no, with 0 equal to A in the DMR specification, 1 for B, etc. StreamID 4 Bytes 00000000-FFFFFFFF Random or incremented number which stays the same from PTT-press to PTT-release which identifies a stream.
DMR Data	33 Bytes		The on-air DMR data with possible FEC fixes to the AMBE data and/or Slot Type and/or EMB, etc.

Additional Information

Name	Comment
RptrId	3 Bytes registered DMR-ID for public repeaters, 4 Bytes for private repeaters. This is the User-ID of the owner with a 1 Byte prefix or suffix. Details will follow after coordination with DMR admin team. 901xxx worldwide system IDs for dongle, hotspot and other add on networks (coordinated by DMRplus network team, not registered individually, example: 901004 for DV4 dongle network).
Location, Description, Software-ID	In all free-text fields the author of the application software has to make sure that the content is free of URLs, HTML tags, special characters and local language characters.

License

• https://creativecommons.org/licenses/by-nc-sa/4.0/

You are free to:

• Share — copy and redistribute the material in any medium or format
• Adapt — remix, transform, and build upon the material
• The licensor cannot revoke these freedoms as long as you follow the license terms.

Under the following terms:

• Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
• NonCommercial — You may not use the material for commercial purposes.
• ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.