0
edits
Changes
DSM Communication Protocol (view source)
Revision as of 15:20, 6 December 2022
, 15:20, 6 December 2022Created page with " = File upload procedure = When video/snapshot file is requested via SMS/GPRS command firstly the device checks if it has SD card inserted and if it has the requested video/sn..."
= File upload procedure =
When video/snapshot file is requested via SMS/GPRS command firstly the device checks if it has SD card inserted and if it has the requested video/snapshot in the SD card. The file is present, file upload is immediately triggered, otherwise the device checks if DSM camera is connected to FMX6yz and tries to download the file – file upload to the server starts only after the file was saved to FMXs SD card.
== General command structure ==
General communication packet structure is as in table below. It consists of the command ID (2 bytes), data length of command and payload.
Table 5 General command structure
{| class="wikitable"
|'''Command ID (2 bytes)'''
|'''Data length (2 bytes)'''
|'''Data ([data length] number of bytes)'''
|-
|0xFFFF
|0xFFFF
|<command data>
|}
== Modified file transfer protocol ==
=== Initialization packet ===
On connection, the device sends an initialization packet.
Table 6 Initialization packet structure
{| class="wikitable"
|'''Header (2 bytes)'''
|'''Protocol ID (2 bytes)'''
|'''IMEI (8 bytes)'''
|'''Settings (4 bytes)'''
|-
|0x0000
|0xFFFF
|0xFFFFFFFFFFFFFFFF
|0xFFFFFFFF
|}
Protocol ID – just a reference for the protocol version that is running on device (for server cross compatibility with older versions).
Settings flag contains information on what is available for download. Structure provided:
Table 7 Settings bytes structure
{| class="wikitable"
| colspan="32" |'''Settings, 4 B'''
|-
| colspan="8" |'''Byte 3'''
| colspan="8" |'''Byte 2'''
| colspan="8" |'''Byte 1'''
| colspan="8" |'''Byte 0'''
|-
|
|
|
|
|
|
|*
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|}
<nowiki>*</nowiki> This bit will be set to 1 to indicate, that device has a file ready to upload to server. Server has to send file path request (0x000C) command to know what file is ready for upload.
=== Close session command (CMD_ID 0x0000) ===
In case when device connects to the server, but server does not expect it to connect, server will respond by sending close command (0x0000) after which connection will be terminated. This command is also used when the device connects to server for custom file sending and server finishes to send all custom files to device.
Table 8 Close session command structure
{| class="wikitable"
|'''Command ID (2 bytes)'''
|'''Data length (2 bytes)'''
|-
|0x0000
|0x0000
|}
=== Request file path (CMD_ID 0x000C) ===
First after connecting to server and seeing bit set in init packet the server should send file path request command (0x000C).
Table 9 Request file path command structure
{| class="wikitable"
|'''Command ID (2 bytes)'''
|'''Data length (2 bytes)'''
|'''Blank field (2 bytes)'''
|-
|0x000C
|0x0002
|0x0000
|}
=== File path response (CMD_ID 0x000D) ===
This is a response to file path request (0x000C) command.
Table 10 File path response command structure
{| class="wikitable"
|'''Command ID (2 bytes)'''
|'''Data length (2 bytes)'''
|'''Blank field (Variable)'''
|-
|0x000D
|1-512
|<file path, or \0>
|}
=== File metadata request command (CMD_ID 0x000A) ===
This command is used for retrieving extra information about the file requested by the server with the command 0x000C.
Table 11 File metadata request command structure
{| class="wikitable"
|'''Command ID (2 bytes)'''
|'''Data length (2 bytes)'''
|-
|0x000A
|0x0000
|}
=== File metadata response command (CMD_ID 0x000B) ===
This command is a response to the metadata request command 0x000A.
Response command returns information about a file: Unix timestamp, file type, trigger, GPS coordinates and video length. All values are sent as unsigned integers.
Table 12 File metadata response command structure
{| class="wikitable"
|'''Command ID'''
|'''Data length'''
|'''Unix timestamp'''
'''(4 bytes)'''
|'''File type'''
'''(1 byte)'''
|'''Trigger'''
'''(1 byte)'''
|'''Latitude'''
'''(4 bytes)'''
|'''Longitude'''
'''(4 bytes)'''
|'''DSM event'''
'''(2 bytes)'''
|'''Driver name (10 bytes)'''
|-
|0x000B
|0x000F
|0xFFFFFFFF
|0xFF
|0xFF
|0xFFFFFFFF
|0xFFFFFFFF
|0xFFFF
|0xFFFFFFFFFFFFFFFFFFFF
|}
Table 13 File metadata description
{| class="wikitable"
|'''Data'''
|'''Description'''
|-
|Unix timestamp
|Timestamp at the time of triggering an upload or the timestamp of an SMS request. For periodic images (current snapshots) the timestamp is updated when file info is received from the camera.
|-
|File type
|File media type.
2 – current snapshot
|-
|Trigger
|These trigger values are not to be confused with the values of [[DSM Communication Protocol#%20Camera%20configurable%20parameters|configurable trigger parameters]].
0 – none
1 – DIN1
2 – DIN2
3 – DIN3
4 – DIN4
5 – crash
6 – towing
7 – idling
8 – geofence
9 – unplug
10 – green driving
11 – server request (camreq SMS or GPRS command)
12 – periodic
13 – DSM event
|-
|Latitude
| rowspan="2" |GPS coordinates at the time of triggering an upload. For periodic images (current snapshots) the coordinates are updated when file info is received from the camera. To get coordinates with a decimal point, these values should be divided by 1000000.
|-
|Longitude
|-
|DSM Event
|Multiple DSM events can be triggered at the same time and represented with multiple set bits:
0 bit – Drowsiness
1 bit – Distraction
2 bit – Yawning
3 bit – Phone
4 bit – Smoking
5 bit – Driver absence
6 bit – Mask
7 bit – Seat belt
8 bit – G-sensor
|-
|Driver name
|A 10-character reversed string for the recognized driver’s name.
|}
=== File request command (CMD_ID 0x0008) ===
After device is connected for file upload server initiates file transfer by sending this command.
Table 14 File request command structure
{| class="wikitable"
|'''Command ID (2 bytes)'''
|'''Data length (2 bytes)'''
|'''File identifier'''
|-
|0x0008
|0xFFFF
|''File path has to be requested first via 0x000C command.''
|}
''Device should answer with start command (0x0001) indicating size and CRC of requested file.''
=== Start file transfer command (CMD_ID 0x0001) ===
After device received file request command from server (0x0008) device sends start command (0x0001) with file data (file size in bytes, CRC).
Table 15 Start file transfer command structure
{| class="wikitable"
|'''Command ID (2 bytes)'''
|'''Data length (2 bytes)'''
|'''File Size (4 bytes)'''
|'''File CRC (2 bytes)'''
|-
|0x0001
|0x0006
|0xFFFFFFFF
|0xFFFF
|}
=== Resume file transfer command (CMD_ID 0x0002) ===
In a response to the start command (0x0001) a resume command (0x0002) must be sent from server.
Table 16 Resume file transfer command structure
{| class="wikitable"
|'''Command ID (2 bytes)'''
|'''Data length (2 bytes)'''
|'''Packet offset (4 bytes)'''
|-
|0x0002
|0x0004
|0x00000000
|}
To begin file transfer from the start, offset should be set to 0 (4 bytes value). In case when the file transfer was interrupted, to resume file transfer, offset can be set to the desired value (1 ≤ <offset> ≤ <file_packets>).
=== Synchronize file transfer command (CMD_ID 0x0003) ===
In a response to the resume command (0x0002), sync command (0x0003) is sent from device.
Table 17 Synchronize file transfer command structure
{| class="wikitable"
|'''Command ID (2 bytes)'''
|'''Data length (2 bytes)'''
|'''File offset (4 bytes)'''
|-
|0x0003
|0x0004
|0xFFFFFFFF
|}
By sending the sync command it is ensured that next data command will contain file data starting from the specified offset.
=== File data transfer command (CMD_ID 0x0004) ===
After sending the sync command (0x0004) file data transfer is started by sending data commands (0x0004).
Table 18 File data transfer command structure
{| class="wikitable"
|'''Command ID (2 bytes)'''
|'''Data length (2 bytes)'''
|'''File data (up to 1024 bytes)'''
|'''Data CRC (2 bytes)'''
|-
|0x0004
|Up to 0x0402
|0xFF…
|0xFF
|}
File data is split into 1024-byte parts, each part wrapped into data command and sent.
'''''Note:''' if command with a bad CRC is received, the resume command (0x0002) should be sent with last valid file offset. After receiving the resume command, server will stop sending data commands (0x0004) and continue communication from “Resume file transfer command (CMD_ID 0x0002)” step.''
''CRC polynomial expression: '''0x8408'''''
''When calculating CRC, the initial value is the same as the CRC value from the previously received packet (0x0004).''
=== File transfer status command (CMD_ID 0x0005) ===
After file transfer is completed and no more files are required from device, server should send the file transfer command (0x0005) with completed status (0x00000000) to the device.
'''Note:''' this command does not work after executing repeat init command (0x0009) – in this case the server should send close session command (0x0000) mentioned above.
Table 19 File transfer status command structure
{| class="wikitable"
|'''Command ID (2 bytes)'''
|'''Data length (2 bytes)'''
|'''Status (4 bytes)'''
|-
|0x0005
|0x0004
|0xFFFFFFFF
|}
In case of server using invalid arguments, commands or not following the file request flow, the device will send this command with status field set to one of the few possible error codes (provided below).
Table 20 File transfer possible status values
{| class="wikitable"
|'''Status value (hexadecimal)'''
|'''Description'''
|'''Notes'''
|-
|0x00000000
|File transfer process completed
|Sent from server
|-
|0x00000002
|Failed to close GPRS
|Sent from device
|-
|0x00000003
|Failed to close socket
|Sent from device
|-
|0x00000005
|Invalid response from server to init packet
|Sent from device
|-
|0x00000011
|This error code forces the device to disconnect from server
|Sent from device. Possible causes:
· The requested file is not available by camera
|}
After receiving the transfer completed command device should disconnect from the server.
=== Initialization packet repeat command (CMD_ID 0x0009) ===
When sent, the initialization packet is repeated. This is used, when all of the files are downloaded and additional check is carried out for any additional files, that may have been captured during the download operation.
