Codec 12

From Wiki Knowledge Base | Teltonika
Jump to: navigation, search

Codec 12[edit]

  • About Codec12

Codec12 is original Teltonika protocol for device-server communication over GPRS messages.

Codec12 GPRS commands can be used for sending configuration, debug, digital outputs control commands or other (special purpose command on special firmware versions). This protocol is also necessary for using FMB63/FM63/FM5300/FM5500/FM4200 features like: Garmin, LCD communication, COM TCP Link Mode.

Note: GPRS commands are supported only through TCP connection

  • FM firmware requirements

Supported GPRS commands on each device depend on firmware version. For available GPRS commands on each device, please refer to Table1 FM firmware requirement “SMS over GPRS” means that all standard SMS commands text can be sent to device via GPRS in Codec12 format.

Device SMS over GPRS SMS over GPRS via UDP Special Codec12 GPRS commands
FM11YX Available since base firmware 01.11.XX Since base firmware

1.26.00

Available in FM1100 and FM1110 special firmware version 12.XX.XX*
FM12YX Available since base firmware 01.03.XX - Available in FM12YX special firmware 09.XX.XX*
FM10YX Available since base firmware 00.03.XX - Available since base firmware 00.06.XX and later versions**
FM3400 Available since base firmware 01.01.XX - -
FM36YX Available in base firmware Since base firmware 01.06.01 -
FM5300 Available in all firmware versions - Available in all firmware versions**
FM5500 Available in all firmware versions - Available in all firmware versions**
FM2200 Not available - Special firmware version 07.XX.XX*
FM4200 Not available - Special firmware version 42.XX.XX*
FM63YX Available in all firmware versions Since base firmware 00.02.19 Available in all firmware versions**
FMB9YX Available in base firmware Available in base firmware -
FMB0YX Available in base firmware Available in base firmware -
FMB1YX Available in base firmware Available in base firmware -
FMB6YX Available in all firmware versions Since base firmware 00.02.19 Available in all firmware versions**
FMA1YX Available in base firmware Since base firmware 1.26.00 Available in special firmware version 12.XX.XX*
FMA2YX Available in base firmware Available in base firmware -

Table 1. FM firmware requirement

'*' - supported special commands are listed on special firmware description. Please contact Your Teltonika sales manager for more details;

'**' - supported special commands are listed on device user manual, chapter “GPRS Commands”


  • GPRS command session

Following figure shows how GRPS command session is started over TCP. wq.png

First FM opens GPRS session and sends AVL data to server (refer FM protocols). Once all records are sent and correct sent data array acknowledgment is received by FM then GPRS commands in Hex can be sent to FM.

The ACK (acknowledge of IMEI from server) is a one byte constant 0x01. The acknowledgement of each data array send from FMXXXX is four bytes integer – number of records received.

Note, that GPRS session should remain active between FM and server, while GPRS commands are sent. For this reason active datalink timeout (global parameters in FMXXXX configuration) is recommended to be set to 259200 (maximum value).


  • General Codec12 message structure

The following diagram shows basic structure of Codec 12 messages.


Command message structure

0x00000000 Data size 0x0C Command quantity 0x05 Command size Command Command quantity CRC
4 bytes 4 bytes 1 byte 1 byte 1 byte 4 bytes X bytes 1 byte 4 bytes


Response message structure

0x00000000 Data size 0x0C Command quantity 0x06 Command size Command Command quantity CRC
4 bytes 4 bytes 1 byte 1 byte 1 byte 4 bytes X bytes 1 byte 4 bytes


Structure explanation:

The message starts with preamble field - four zero bytes. Then goes four bytes data size field (size is calculated from 0x0C field to the second command or response quantity field). Then follows one byte Codec ID field (in Codec 12 it is always 0x0C). Then goes command or response quantity field (it is ignored when parsing the message). After that goes one byte message type field. It can be 0x05 to denote command or 0x06 to denote response. Then follows four bytes command or response size field. After it follows the command or response field itself. After that goes the second command or response quantity field. At the end there’s four bytes CRC field.

Note that difference between commands and responses is message type field: 0x05 means command and 0x06 means response.

The algorithm to calculate CRC is CRC-16 (also known as CRC-16-IBM). All the fields from codec ID to second command/response quantity field are used to calculate CRC. The algorithm of how to calculate


CRC is shown in Figure 3 CRC calculation algorithm.

qqq.png Figure 3 CRC calculation algorithm


  • Command coding table

Command has to be convert from ASCII characters (char) to hexadecimal (Hex)

Table 2 ASCII conversion table

asa.png


  • Command parsing example

Hexadecimal stream of command and answer in this example are given in hexadecimal form. The different fields of message are highlighted in gray and yellow for better readability and command is converted in ASCII for better understanding.

Server command

Hexadecimal stream:

sx.png

Parsed:

Preamble: 0x00000000

Packet Length: 0x00000018

Codec: 0x0C

Quantity of commands: 0x01

Command type: 0x05

Command size: 0x00000010

Command in ASCII after conversion: #GET DATAORDER<CR><LF>

Quantity of commands: 0x01

CRC: 0x00004990


Device answer

Hexadecimal stream:

sds.png

Parsed:

Preamble: 0x00000000

Packet Length: 0x00000016

Codec: 0x0C

Quantity of commands: 0x01

Command type: 0x06

Command size: 0x0000000E

Command response is in ASCII after conversion: #DATAORDER=1<CR><LF>

Quantity of commands: 0x01

CRC: 0x00000095


  • Codec12 GPRS commands examples

The example commands given in hexadecimal form separated by dollar signs are suitable to be sent from TCP server during data exchange session between FMXXXX device and server (for more details see Figure 1 Command session) The command can be sent from a terminal program such as Hercules (in TCP server mode). Simply write command as explained below into Hercules Send field and click Send button. The TCP server must be listening on specified port (see field Port and button Listen in Figure 4).

he.png

Figure 4 Hercules terminal GUI


  • SMS over GPRS in Codec12 examples

In case of sending SMS commands over GPRS, do not use SMS logins set during configuration or do not leave empty spaces before command. Devices and firmware versions that support SMS over GPRS are listed in Table1.

Example 1: getinfo

Sending “getinfo” SMS command via GPRS Codec12:

Server requests:

Hexadecimal stream:

00000000000000110C010500000009676574696E666F0D0A010000DA7E

Parsed:

Zero: 0x00000000

Packet Length: 0x00000011

Codec: 0x0C

Quantity of commands: 0x01

Command type: 0x05

Command size: 0x00000009

Command: 0x676574696e666f (HEX of getinfo)

Command end symbol: 0x0D0A

Quantity of commands: 01

CRC: 0x0000DA7E


Device response:

Hexadecimal stream:

00000000000000820C01060000007A494E493A323031312F312F3120303A30205254433A323031312F312F3120373A3333205253543A33204552523A302053523A3134372042523A302043463A312046473A3020464C3A302055543A3020534D533A30204E4F4750533A303A3134204750533A32205341543A302052533A36204D443A302052463A30010000B8AA


Parsed:

Zero: 0x00000000

Packet Length: 0x00000082

Codec: 0C

Quantity of commands: 01

Command type: 06

Command size: 0x0000007A

Command response in ASCII after conversion: INI:2011/1/1 0:0 RTC:2011/1/1 7:33 RST:3 ERR:0 SR:147 BR:0 CF:1 FG:0 FL:0 UT:0 SMS:0 NOGPS:0:14 GPS:2 SAT:0

RS:6 MD:0 RF:0 (without <CR><LF>)

Quantity of commands: 01

CRC: 0x0000B8AA


Example 2: getio

Sending “getio” SMS command via GPRS Codec12:

Server request:

Hexadecimal stream:

000000000000000F0C010500000007676574696F0D0A0100003349

Parsed:

Zero: 0x00000000

Packet Length: 0x0000000F

Codec: 0x0C

Quantity of commands: 0x01

Command type: 0x05

Command size: 0x00000007

Command: 0x676574696f (HEX of getio)

Command end symbol: 0x0D0A

Quantity of commands: 01

CRC: 00003349


Device response:

Hexadecimal stream:

000000000000002C0C0106000000244449313A30204449323A30204449333A302041494E3A323420444F313A3020444F323A30010000F925

Parsed:

Zero: 0x00000000

Packet Length: 0x0000002C

Codec: 0C

Quantity of commands: 01

Command type: 06

Command size: 0x00000024

Command response in ASCII after conversion: DI1:0 DI2:0 DI3:0 AIN:24 DO1:0 DO2:0 (without <CR><LF>)

Quantity of commands: 01

CRC: 0x0000F925



  • Special Codec12 commands:


Example 1: #GET VERSION

Server command - #GET VERSION<CR><LF>

Device response - #VERSION=XXXXXXXX<CR><LF>

XXXXXXXX – Device Firmware Version (up to 8 characters)

$00$00$00$00$00$00$00$16$0C$01$05$00$00$00$0E$23$47$45$54$20$56$45$52$53$49$4f$4e$0D$0A$01$00$00$D0$C8


Example 2: #GET NETWORK

Server command - #GET NETWORK<CR><LF>

Device response - #NETWORK=XXXXXX<CR><LF>

XXXXXX – GSM Operator Network [0 - 999999]

$00$00$00$00$00$00$00$16$0C$01$05$00$00$00$0E$23$47$45$54$20$4e$45$54$57$4f$52$4b$0D$0A$01$00$00$ED$61