TCP/UDP Protocol Documentation

Gateway
  1. Ip: g.cloud.tzonedigital.cn
  2. Port: 18800
Client-server interaction process


Uplink Data Protocol

1、Data Protocol Framework

      1.1  FixedHeader header format is fixed and contains the content length of the protocol

Description: A protocol with a fixed header format and content length, encoded as Hex. This protocol defines a request as two parts. The first part defines basic information including the length of the second part. We usually call the first part the header "request header(request name + len) + request body" .

 

Header Mark

Length

Type

Data

End Mark

545A

0090

0004

00..........

0D0A

 

Example

545A0090000416010C011C02573373695247563261574E6C535551694F6949344E6A41774D4441774D4441774D4441774D4441694C434A5356454D694F6A45324E4445354E446B314E6A41774D444173496C526C625841694F6A49324C6A5573496C4A49496A6F314D437769566D39736447466E5A5349364D7934324C434A4D5958524D626D63694F6949696656303D0001EADF0D0A

 

2、Data Type

2.1  Login

 

Type

Format

Example

1

0000

545A(2bytes)

+Length(2bytes)

+0000(2bytes)

+Hardware Type(2bytes)

+Firmware Version(4bytes)

+IMEI(8bytes)

+CRC(2bytes)

+0D0A(2bytes)

545A001200000000020000000641884907900001C4990D0A

illustrate:

Packet Length: The length of the data from the data type (including the data type) to the end of the check digit.

Check code: from the data type (including the data type) to the data before the check digit

Purpose: Each time a connection is established, the model, firmware version, and IMEI are first sent to the server, which can be omitted from the data later. Reduce the amount of data.

2.2  Request a Ping speed test

 

Type

Format

Example

2

0001

545A(2bytes)

+Length(2bytes)

+0001(2bytes)

+Time(6bytes)

+Data(N bytes)

+CRC(2bytes)

+0D0A(2bytes)

Request 32 characters of data

545A 002A000113010A121E01

00000000000000000000000000

000000000000000 00000000000

000000000000 FBD30D0A

Note: Please obtain the server time before testing. 


2.3  Reply to downlink command processing status

 

Type

Format

Example

3

0002

545A(2bytes)

+Length(2bytes)

+0002(2bytes)

+Time(6bytes)

+Condition(1 bytes)

+Serial Number(1 bytes)

+CRC(2bytes)

+0D0A(2bytes)

545A000C000213010A121E010101AF170D0A

Description: Status 01 means success, 00 means failure

 

2.4  Heartbeat Packet

 

Type

Format

Example

4

0003

545A(2bytes)

+Length(2bytes)

+0003(2bytes)

+CRC(2bytes)

+0D0A(2bytes)

545A00040003B1410D0A

 

2.5  Application Package

 

Type

Format

Example

5

0004

545A(2bytes)

+Length(2bytes)

+0004(2bytes)

+RTC(6bytes)

+Application data(N bytes)

+Serial(2bytes)

+CRC(2bytes)

+0D0A(2bytes)

545A

0090

0004

16010C011C02

573373695247563261574E6C535551694F6949344E6A41774D4441774D4441774D444

1774D4441694C434A5356454D694F6A45324E4445354E446B314E6A41774D44417349

6C526C625841694F6A49324C6A5573496C4A49496A6F314D437769566D39736447466

E5A5349364D7934324C434A4D5958524D626D63694F6949696656303D

0001

EADF

0D0A

 

3、Application Data

3.1  Temperature and humidity sensor

 

Format

Example

1

[{

"DeviceID":DeviceID,

"RTC":RTC,

"Temp":Temperature(℃),

"RH":Humidity(%),

"Voltage":Voltage(v),

"LatLng"latitude and longitude:

}]

[{

"DeviceID":"860000000000000",

"RTC":1641949560000,

"Temp":26.5,

"RH":50,

"Voltage":3.6,

"LatLng":"22.547,114.085947"

}]

2

[{

"DeviceID":"860000000000000",

"RTC":1641949560000,

"Temp":26.5,

"RH":50,

"Voltage":3.6,

"LatLng":"22.547,114.085947"

},{

"DeviceID":"860000000000001",

"RTC":1641949560000,

"Temp":27.5,

"RH":50,

"Voltage":3.6,

"LatLng":"22.547,114.085947"

}]


[{"DeviceID":"860000000000000","RTC":1641949560000,"Temp":26.5,"RH":50,"Voltage":3.6,"LatLng":""}]

After processing the data using Base64 encoding:

W3siRGV2aWNlSUQiOiI4NjAwMDAwMDAwMDAwMDAiLCJSVEMiOjE2NDE5NDk1NjAwMDAsIlRlbXAiOjI2LjUsIlJIIjo1MCwiVm9sdGFnZSI6My42LCJMYXRMbmciOiIifV0=

Convert to byte array:

573373695247563261574E6C535551694F6949344E6A41774D4441774D4441774D4441774D4441694C434A5356454D694F6A45324E4445354E446B314E6A41774D444173496C526C625841694F6A49324C6A5573496C4A49496A6F314D437769566D39736447466E5A5349364D7934324C434A4D5958524D626D63694F6949696656303D

 

Server Downlink Data Protocol

1、Data Protocol Framework

    1.1  Command Line Protocol

  Description: Command line protocol, encoded as Ascii. The command line protocol defines that each request ends with a carriage return line feed "\r\n"

Header

Type

 

Data

End


@

 

,

 

#

\r\n

Example:

Downlink data current UTC time

@UTC,2019-01-10 09:52:01#

 

2、Data Type

     2.1 Server current UTC time

 

Type

Format

Request

Example

1

UTC

@UTC,yyyy-MM-dd HH:mm:ss#

TCP Connection

@UTC,2019-01-10 09:52:01#

 

2.2  ACK 

 

Type

Format

Request

Example

2

ACK

@ACK,N#

Please review the hardware protocol documentation

@ACK,1#

Description: N is the serial number in the uplink data, > 0, it means the receiving and processing is successful; if it is -1, it means that the processing fails.

 

2.3 Error

 

Type

Format

Request

Example

3

ERROR

@ERROR,N#

  Any request

@ERROR,001#

Description: N is the error code.

Error Code

Description

Terminal Handling Requirements

000

unknown

Disconnect, reconnect to server

001

The server receiving service is unavailable, temporarily unable to receive data

Try connecting to the server after a 5 minute pause. (Due to uncertain factors, the internal functional modules of the gateway may not work normally, and the data sent to the server at this time cannot be saved.)

002

The current number of connections exceeds the maximum number the server can handle.

Try connecting to the server after a 5 minute pause.

003

The client sends data too fast.

Adjust the sending interval

004

data parsing error

Drop the data and send the next one. (When parsing data, the terminal should not send the same data repeatedly.)

005

The data time is not within the range received by the server

Discard historical data (depending on application requirements)

006

 Unknown client device

Stop connecting to server (not supported by new product server)

007

The device has been disabled

Try connecting to the server after a 5 minute pause.

 

2.4  Ping network speed test

 


Type


Format


Request


Example

4

PING

@PING,size,time#

Refer to "Terminal Uplink Data Protocol"

Requesting 32 characters of data takes 30 milliseconds.@PING,32,30#

Description: size is the size of the upstream character data, time is time-consuming, unit: milliseconds.

Purpose: You can know the current network situation and expand the application.


2.5  Downlink

 

Type

Format

Request

Example

5

CMD

@CMD,Command,N#

Any request

Change password command

@CMD,*000000,001,123456#,1#

Description: Command is a command. N is the assigned number, which is used to distinguish commands and is used in terminal reply.