DSM, DSMX and DSM Forward Programming are propietary protocol from the **Spektrum** radio brand. Since they don't make this information public, we have to reverse engineer it by analyzing the data exchanged between the RX and TX.
This document descrives what we know so far.
Thanks to **Pascal Langer** (Author of the Multi-Module) for the initial reverse engineering of the protocol and first version of the code that has been used for a while (Version 0.2)
The menu to be displayed is stored at the RX, the GUI only renders the menu title and menu lines received. The tipical conversation with the RX will be to ask for a menu (using the menuId number), and then wait for the data to come. The first thing will be the Menu (header) data, later we request the next 6 lines (one at a time), and optionally the values for each line.
A typical exchange will look like this in the log:
-`NL`: Computed Normalized LIST (0 reference) for List Values. Source is the RAW range. For example, for lines of list of values. `[3->4,3]` is tranlated to `NL=(0->1,0,S=3)` since the value is also normalize to 0. `"S="` means the initial entry in the `List_Text` array
-`Val`: Current value for line who hold data. Relative to 0 for List Values. For List Values, the log will show the translation of the value to display text. example: `Val=1|"Act"` that is coming from `List_Value[4]`
-`LINE_TYPE.MENU (Log: "T=M")`: This could be regular text or a navigation to another menu. if `ValueId` is the same as the current MenuId (`MId=`), is a plain text line (navigation to itself). If the `ValueId` is not the current menuId, then `ValueId` is the MenuId to navigate to.
We have found only one exception to the plain text rule, a true navigation to itself, in that case, in the text of the menu, you can use the "/M" flag at the end of the text to force it to be a menu button.
-`LINE_TYPE.LIST_MENU_NC (Log T=LM_nc)`: This is a line that shows as text in the GUI. The numeric value is translated to the proper text. The range is important, since it descrives the range of posible values. No incremental RX changes, only at the end.
Example: List of Values, List_Text[] starts at 53, ends at 85, with a default of 85. When normalized to 0, is a range from 0->32 for the numeric value. The Display value `Aux1` is retrive from `List_Text[6+53]`.
-`LINE_TYPE.LIST_MENU_TOG (Log T=L_tog)`: Mostly the same as LIST_MENU_NC, but is just 2 values. (ON/OFF, Ihn/Act, etc). Should be a toggle in the GUI.
-`LINE_TYPE.LIST_MENU (Log T=LM)`: Mostly the same as LIST_MENU_NC, but incremental changes to the RX. Some times, it comes with a strange range `[0->244,Default]`. Usually this means that the values are not contiguos range; usually Ihn + Range. Still haven't found where in the data the correct range comes from.
-`LINE_TYPE.VALUE_NUM_I8_NC (Log: "T=V_nc")`: This line is editable, but is not updated to the RX incrementally, but only at the end. The Flight Mode line is of this type, so we have to check the TextId to differenciate between Flight mode and an Editable Value.
Values who are editable, are updated to RX as they change. For example, when changing attitude trims, the servo moves as we change the value in real-time.
LIST_MENU_NC, VALUE_NUM_I8_NC don't update the RX as it changes. It changes only in the GUI, and only update the RX at the end when confirmed the value. (NO-INC-CHANGES Bit)
After finishing updating a value, a validation command is sent. RX can reject the current value, and will change it to the nearest valid value.
## Special Menus
Seems like menuId=0x0001 is special. When you navigate to this menu, the RX reboots.
When this happens, we need to start from the beginning as if it was a new connection.
# Send and Receive messages
To comunicate with the Multi-Module, Lua scripts in OpenTx/EdgeTx has access to the `Multi_Buffer`. Writting to it will send data to RX, received data will be read from it.
For our specific case, this is how the Multi_Buffer is used:
|0..2|3|4..9|10..25
|--|--|--|--
|DSM|0x70+len|TX->RX data|RX->TX Data
To write a new DSM Fwd Programing command, write the data to address 4..9, and later set the address 3 with the length.
When receiving data, address 10 will have the message type we are receiving, or 0 if nothing has been received.
## Starting a new DSM Forward programming Connection
- Write 0x00 at address 3
- Write 0x00 at address 10
- Write "DSM" at address 0..2
## Disconnect
- Write 0x00 at address 0
# Request Messages (TX->RX)
## DSM_sendHeartbeat()
keep connection open.. We need to send it every 2-3 seconds, otherwise the RX will force close the connection by sending the TX an Exit_Confirm message.
|4|5|6|7|8|9|10
|--|--|--|--|--|--|--
Msg| Len? | ?? | ??
0x00|0x04|0x00|0x00
SEND DSM_sendHeartbeat()
DSM_SEND: [00 04 00 00 ]
## DSM_getRxVersion()
Request the RX information
|4|5|6|7|8|9|10
|--|--|--|--|--|--|--
Msg| Len? | ?? | ?? |??|??
0x11|0x06|0x00|0x14|0x00|0x00
SEND DSM_getRxVersion()
DSM_SEND: [11 06 00 14 00 00 ]
## DSM_getMainMenu()
Request data for the main menu of the RX
|4|5|6|7|8|9|10
|--|--|--|--|--|--|--
Msg| Len? | ?? | ?? |??|??
0x12|0x06|0x00|0x14|0x00|0x00
SEND DSM_getMainMenu()
DSM_SEND: [12 06 00 14 00 00 ]
## DSM_getMenu(menuId, lastSelLine)
Request data for Menu with ID=`menuId`. lastSelLine is the line that was selected to navigate to that menu. Most menus works with 0, but for some special "Enter Bind Mode", "Factory Reset", "Save to Backup" they will not work if we send 0, has to be the line who was selected in the confirmation menu line "Apply".
Request the first line of a menu identified as `menuId`. The response will be the first line of the menu. Some times, it return lines shown as `'MenuUknownLine_0x05'` that we still are trying to understand what they are for.
|4|5|6|7|8|9|10
|--|--|--|--|--|--|--
Msg|Len? | MSB (menuId) | LSB (MenuId)
0x13|0x04|0x10|0x60
SEND DSM_getFirstMenuLine(MenuId=0x1000)
DSM_SEND: [13 04 10 00 ]
## DSM_getNextMenuLine(menuId, curLine)
Request the retrival of the next line following the current line. Response is either the next line, or the next value, or nothing.
Retrive the next value after the last `ValId` of the current `menuId`. text is just for debugging purposes to show the header of the value been retrived.
The Response is a Menu Value or nothing if no more data.
Validates the value identified as `valId`. `text` and `line` are there to add debugging info. The RX can response an Update value if the value is not valid and needs to be corrected.
Durin editing, this serves as a heartbeat that we are editing the value. The value identified as `valId`. `text` and `line` are there to add debugging info. The RX can response an Update value or a NUL response.
Can be use as a response, or heartbeat from the RX to keep the connection open.
|10|11
|--|--
|Resp|Msg
|0x09|0x00
RESPONSE RX: 09 00
RESPONSE NULL
# Unknown Lines
TOTALLY UNKNOWN WHAT THIS ARE FOR.. but only works for the Main Menu..
Other menus they just loop on line=0 forever.
## DSM_getNextUknownLine_0x05(menuId, curLine)
Request the retrival of the next Unknown line following the current line. Response is either the next unknow line, next menu line, or the next value, or nothing.
We still don't know what is this for, but we have to retrive them and skip then. Works for main menu, but when it happens in another menus, usually we stay in an infinite loop retrieving line=0
|10|11|12|13|14|15|16|17
|--|--|--|--|--|--|--|--
|Resp|Msg|LSB (line#)
|0x09|0x05|0x00|0x01|0x00|0x00|0x00|0x07
|0x09|0x05|0x01|0x01|0x00|0x00|0x00|0x07
## Interaction on Main Menu
This is the normal interaction for the main menu. As you can see, it iterates on the 6 Unknow lines (0..5), and afterwards, it starts sending normal menu lines.
We found that sometimes, Overriding LastSelectedLine to 0 solves the problem for some specific menus. Not for all (for other, is the oposite (0->1)). But at least no unknown lines are returned with this hack for AR631/AR637. Maybe others also needed.
**Overriding to Zero is not a good solution for every menu. Some menus needs the LastLine to know the behaviour (for example, Factory Reset the RX, Save Backup, Restore Backup, Enter Bind Mode, Some sensor Calibration). Thats why we cannot do it blindly.**
Here is the current code to fix some of this problems in AR631/AR637.
Function `DSM_SelLine_HACK()`
if (ctx.RX.Id == RX.AR637T or ctx.RX.Id == RX.AR637TA or ctx.RX.Id == RX.AR631) then
-- AR631/AR637 Hack for "First time Setup" or
-- "First Time AS3X Setup", use 0 instead of the ctx.SelLine=5
if (ctx.Menu.MenuId == 0x104F or ctx.Menu.MenuId==0x1055) then
LOG_write("First time Setup Menu HACK: Overrideing LastSelectedLine to ZERO\n")
