= Digital Voice Modem

== Technical Note
=== Modem Protocol

Document Identifier: TN.1001

Author: Bryan Biedenkapp, N2PLL

Editors: Bryan Biedenkapp, N2PLL

Contributors: N/A

Abstract: Describes high-level concepts and procedures for the Modem Protocol.

Status: Draft

== 1. Introduction
This document describes, in high-level, the general concepts and procedures for the Modem Protocol used by DVM projects.

== 2. Technical Note

=== 2.1 Definitions
* DVM: Digital Voice Modem

=== 2.2 General Concept
The DVM Modem Protocol defines a common and standard communications protocol between a host application and a dedicated modem hardware device (usually based around a STM32F446 or similar).

The core purpose of the protocol is to provide a common serial communications between the host application and the dedicated modem hardware.

=== 2.3 Modem Packet Framing
The modem protocol implements a very simplistic framing mechanism for transmitting data between the host and modem (and vice versa).

[cols="2,1,3"]
|===
|Frame Type |Opcode |Description

|Short
|$FE
|This frame type is used for transporting packets of 254 bytes or less in length.

|Long
|$FD
|This frame type is used for transporting packets greater than 254 bytes in length.
|=== 

[discrete]
==== Modem Packet - Short Frame
[listing]
    Byte 0               1               2               3
    Bit  7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
        | Frame Type  | Length          | Opcode        | ...           |
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
        | <Variable Length Data>                                        |
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    2 bytes (not including data length)

[discrete]
==== Modem Packet - Long Frame
[listing]
    Byte 0               1               2               3
    Bit  7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
        | Frame Type  | Length                          | Opcode        |
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
        | <Variable Length Data>                                        |
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    3 bytes (not including data length)

It is important to note the Length parameter of the packet buffer should be the length of the *entire* packet not just the payload.

==== 2.3.1 Modem Opcodes
The opcode defines which operation/command being transmitted.

[cols="2,1,3"]
|===
|Function Name |Opcode |Description

|Get Version
|$00
|This function is used for retrieving the firmware version from the modem.

|Get Status
|$01
|This function is used for retrieving the current status from the modem.

|Set Configuration
|$02
|This function is used for setting configuration parameters to the modem.

|Set Mode
|$03
|This function is used for setting the operational mode parameter to the modem.

|Set Symbol Level Adjustment
|$04
|This function is used for setting the symbol level adjustment parameters to the modem.

|Set Rx Level Adjustment
|$05
|This function is used for setting the receive level adjustment parameter to the modem.

|Set RF Parameters
|$06
|This function is used for setting the RF parameters to the modem. (Hotspot Only)

|Calibration Data
|$08
|This function is used for setting calibration data to the modem when operating in a calibration mode.

|RSSI Data
|$08
|This function is used for receiving RSSI data from the modem.

|Send CW ID
|$0A
|This function is used to cause the modem to emit a CWID burst of morse code.

|Set FIFO Buffers
|$0F
|This function is used for setting the internal FIFO ringbuffer sizes on the modem.

|DMR Slot 1 Data
|$18
|This function is used for sending/receiving DMR Slot 1 protocol data to/from the modem.

|DMR Slot 1 Lost
|$19
|This function is used for signalling loss of synchronization for DMR Slot 1 protocol data.

|DMR Slot 2 Data
|$1A
|This function is used for sending/receiving DMR Slot 2 protocol data to/from the modem.

|DMR Slot 2 Lost
|$1B
|This function is used for signalling loss of synchronization for DMR Slot 2 protocol data.

|DMR Short LC
|$1C
|This function is used for sending/receiving DMR Short LC protocol data to/from the modem.

|DMR Start
|$1D
|This function is used for providing transmitter control and starting the DMR data stream.

|DMR Abort
|$1E
|

|DMR CACH AT Control
|$1F
|This function is used for setting the DMR CACH AT bit on or off.

|DMR Slot 1 Clear
|$20
|This function is used for commanding the modem to clear the DMR Slot 1 FIFO buffers.

|DMR Slot 2 Clear
|$21
|This function is used for commanding the modem to clear the DMR Slot 2 FIFO buffers.

|Project 25 Data
|$31
|This function is used for sending/receiving Project 25 protocol data to/from the modem.

|Project 25 Lost
|$32
|This function is used for signalling loss of synchronization for Project 25 protocol data.

|Project 25 Clear
|$33
|This function is used for commanding the modem to clear the Project 25 FIFO buffers.

|NXDN Data
|$41
|This function is used for sending/receiving NXDN protocol data to/from the modem.

|NXDN Lost
|$42
|This function is used for signalling loss of synchronization for NXDN protocol data.

|NXDN Clear
|$43
|This function is used for commanding the modem to clear the NXDN FIFO buffers.

|Ack
|$70
|This function is used for acknowledging a command.

|Nack
|$7F
|This function is used for negative acknowledgment of a command.

|Flash Read
|$E0
|This function is used for reading 256 bytes of data from the flash storage partition of the modem. (Only on supported hardware.)

|Flash Write
|$E1
|This function is used for writing 256 bytes of data to the flash storage partition of the modem. (Only on supported hardware.)

|Reboot MCU
|$EA
|This function is used for triggering a reboot of the modem MCU.

|Debug 1
|$F1
|This function is used for receiving debug data from the modem. (1 byte)

|Debug 2
|$F2
|This function is used for receiving debug data from the modem. (2 byte)

|Debug 3
|$F3
|This function is used for receiving debug data from the modem. (3 byte)

|Debug 4
|$F4
|This function is used for receiving debug data from the modem. (4 byte)

|Debug 5
|$F5
|This function is used for receiving debug data from the modem. (5 byte)

|=== 

==== 2.3.2 Modem Operational States
The operational state defines which mode/state the modem is currently in.

[cols="2,1,3"]
|===
|State Name |State |Description

|IDLE
|0
|This is the default state for a modem, the modem is not in any active mode in this state.

|DMR
|1
|When in this mode the modem is actively Rx/Tx DMR protocol data.

|Project 25
|2
|When in this mode the modem is actively Rx/Tx Project 25 protocol data.

|NXDN
|3
|When in this mode the modem is actively Rx/Tx NXDN protocol data.

|CW
|10
|When in this mode the modem is actively Tx CWID morse data.

|Project 25 Calibration 1K
|92
|

|DMR DMO Calibration 1K
|93
|

|DMR Calibration 1K
|94
|

|DMR Low Frequency Calibration
|95
|

|RSSI Calibration
|96
|

|Project 25 Calibration
|97
|

|DMR Calibration
|98
|

|NXDN Calibration
|99
|
|=== 

==== 2.3.3 Negative Acknowledgement Reasons
This table defines the reasons a negative acknowledgement may be sent.

[cols="2,1,3"]
|===
|Reason Name |Reason Code |Description

|OK
|0
|

|NAK
|1
|General Failure.

|Illegal Length
|2
|Packet received was of an illegal length, and was discarded by the modem.

|Invalid Request
|4
|Packet received was an invalid request, and was discarded by the modem.

|Ringbuffer Full
|8
|Sent when a command attempts to write to a FIFO buffer that is full.

|Invalid FDMA Preamble
|10
|Sent by the Set Configuration command typically, to indicate the FDMA preamble value was out of range.

|Invalid Mode
|11
|Sent by either Set Configuration or Set Mode command to indicate a mode was specified that is invalid.

|Invalid DMR CC
|12
|

|Invalid DMR Slot
|13
|Sent by the modem to indicate the DMR slot value was out of range.

|Invalid DMR Start
|14
|

|Invalid DMR Rx Delay
|15
|Sent by the modem to indicate the DMR Rx Delay value was out of range.

|Invalid P25 Correlation Count
|16
|Sent by the modem to indicate the P25 Correlation Count value was out of range.

|No Internal Flash
|20
|Sent by the modem when the hardware does not support the Flash Read or Flash Write operations.

|Flash Erase Failed
|21
|Sent by the modem when the configuration partition of the flash was unable to be erased.

|Flash Write Failed
|22
|Sent by the modem when the configuration partition of the flash was unable to be written.

|Flash Write Too Big
|23
|Sent by the modem when the data sent to be written to the configuration partition of the flash was too large to be written.

|DMR Disabled
|63
|Sent by the modem to indicate DMR operations are disabled.

|P25 Disabled
|64
|Sent by the modem to indicate P25 operations are disabled.

|NXDN Disabled
|65
|Sent by the modem to indicate NXDN operations are disabled.

|=== 

=== 2.4 General Opcode Specifications

==== 2.4.1 Get Version
This opcode is utilized to retreive the hardcoded (at compile time) version string from the firmware.

The host shall transmit:
[cols="2,1,2"]
|===
|Name |Length (bytes) |Description

|Short Frame Start
|1
|Short Frame Start

|Length
|3
|Length

|Get Version Opcode
|1
|
|=== 

Upon reception, the modem shall transmit in response:
[cols="2,1,2"]
|===
|Name |Length (bytes) |Description

|Short Frame Start
|1
|Short Frame Start

|Length
|3
|Length

|Get Version Opcode
|1
|$00

|Protocol Version
|1
|

|CPU Type
|1
|

|CPU UDID
|16
|Universal Device Identifier

|Baked Firmware Version String
|83
|
|=== 

==== 2.4.2 Get Status
This opcode is utilized to retreive the various interesting operational runtime values from the modem.

The host shall transmit:
[cols="2,1,2"]
|===
|Name |Length (bytes) |Description

|Short Frame Start
|1
|Short Frame Start

|Length
|3
|Length

|Get Status Opcode
|1
|$01
|=== 

Upon reception, the modem shall transmit in response:
[cols="2,1,2"]
|===
|Name |Length (bytes) |Description

|Short Frame Start
|1
|Short Frame Start

|Length
|3
|Length

|Get Status Opcode
|1
|$01

|Protocol Enablement Flags
|1
|This byte contains flags that indicate which digital protocol is enabled on the modem.

|Modem State
|1
|Current operational state.

|Operation Flags
|1
|This byte contains various operation flags.

|Reserved
|1
|

|DMR Slot 1 FIFO Space
|1
|This byte contains the FIFO space available in DMR frames.

|DMR Slot 2 FIFO Space
|1
|This byte contains the FIFO space available in DMR frames.

|Reserved
|1
|

|Project 25 FIFO Space
|1
|This byte contains the FIFO space available in P25 LDU frames.

|NXDN FIFO Space
|1
|This byte contains the FIFO space available in NXDN frames.

|=== 

==== 2.4.3 Set Configuration
*TODO TODO TODO*

==== 2.4.4 Set Mode
This opcode is utilized to set the operational mode of the modem.

The host shall transmit:
[cols="2,1,2"]
|===
|Name |Length (bytes) |Description

|Short Frame Start
|1
|Short Frame Start

|Length
|4
|Length

|Set Mode Opcode
|1
|$03

|Operational Mode
|1
|$00
|=== 

Upon reception, the modem shall perform whatever operations necessary to transition to the requested mode and transmit a ACK or NACK in response.

==== 2.4.5 Set Symbol Level Adjustment
*TODO TODO TODO*

==== 2.4.6 Set Rx Level Adjustment
*TODO TODO TODO*

==== 2.4.7 Set RF Parameters (Hotspot Only)
*TODO TODO TODO*

==== 2.4.8 Calibration Data
*TODO TODO TODO*

==== 2.4.9 RSSI Data
*TODO TODO TODO*

==== 2.4.10 Send CWID
*TODO TODO TODO*

==== 2.4.11 Set FIFO Buffers
*TODO TODO TODO*

==== 2.4.12 Acknowledgement
This opcode is utilized by the modem to notify the host of a positive acknowledgement of a command.

The modem shall transmit:
[cols="2,1,2"]
|===
|Name |Length (bytes) |Description

|Short Frame Start
|1
|Short Frame Start

|Length
|4
|Length

|Ack Opcode
|1
|$70

|Opcode Being Acknowledged
|1
|$00
|=== 

==== 2.4.13 Negative Acknowledgement
This opcode is utilized by the modem to notify the host of a negative acknowledgement of a command.

The modem shall transmit:
[cols="2,1,2"]
|===
|Name |Length (bytes) |Description

|Short Frame Start
|1
|Short Frame Start

|Length
|5
|Length

|Nack Opcode
|1
|$7F

|Opcode Being Acknowledged
|1
|$00

|NACK Reason Code
|1
|$00
|=== 

==== 2.4.14 Flash Read
This opcode is utilized to read data from the modem's configuration partition on the flash.

The host shall transmit:
[cols="2,1,2"]
|===
|Name |Length (bytes) |Description

|Short Frame Start
|1
|Short Frame Start

|Length
|3
|Length

|Flash Read Opcode
|1
|$E0
|=== 

The modem shall transmit:
[cols="2,1,2"]
|===
|Name |Length (bytes) |Description

|Short Frame Start
|1
|Short Frame Start

|Length
|249
|Length

|Flash Read Opcode
|1
|$E0

|Variable Length Data
|249
|...
|=== 

==== 2.4.15 Flash Write
*TODO TODO TODO*

==== 2.4.16 Reset MCU
This opcode is utilized to reboot the MCU of the modem.

The host shall transmit:
[cols="2,1,2"]
|===
|Name |Length (bytes) |Description

|Short Frame Start
|1
|Short Frame Start

|Length
|3
|Length

|Reset MCU Opcode
|1
|$EA
|=== 

Upon reception of this opcode the modem should immediately issue a MCU restart. No response back from the modem shall be expected.

=== 2.5 DMR Opcode Specifications

==== 2.5.1 Slot 1 Data
*TODO TODO TODO*

==== 2.5.2 Slot 2 Lost
*TODO TODO TODO*

==== 2.5.3 Slot 2 Data
*TODO TODO TODO*

==== 2.5.4 Slot 2 Lost
*TODO TODO TODO*

==== 2.5.5 Short LC
*TODO TODO TODO*

==== 2.5.6 Start
*TODO TODO TODO*

==== 2.5.7 Abort
*TODO TODO TODO*

==== 2.5.8 CACH AT Control
*TODO TODO TODO*

==== 2.5.9 Slot 1 Clear
*TODO TODO TODO*

==== 2.5.10 Slot 2 Clear
*TODO TODO TODO*

=== 2.6 P25 Opcode Specifications

==== 2.6.1 Data
*TODO TODO TODO*

==== 2.6.2 Lost
*TODO TODO TODO*

==== 2.6.3 Clear
*TODO TODO TODO*

=== 2.7 NXDN Opcode Specifications

==== 2.7.1 Data
*TODO TODO TODO*

==== 2.7.2 Lost
*TODO TODO TODO*

==== 2.7.3 Clear
*TODO TODO TODO*