Dwg Sms API.v2.1 en.1

Dinstar SMS API

Version: 2.1

Author: nate

修订记录

日期修订版本描述作者

2011.5.31 1.0 Initial Version Nate

2012.4.26 2.0 1 Add the Csq Rssi

reported

2 Add the user

Authentication

3.modify the part of SMS

and USSD

Fisher

2012.9.18 2.1 1 Add the sim api:

a. Simcard/simbox info

b. Switch

simcard/Unbind port

c. Reset module/simbox

d. Obtain/modify IMEI

e. Port/slot count

2 Add the SMS repecit

Fisher

1. Overview

This protocol is used for external applications (SMS Server) to control the DWG sending and

receiving SMS/USSD. Protocol is carried over TCP with a request / response way.

2. Message

The message is composed of two parts (head and body).

The head is shown as below

Length 4 byte Length of body

ID 16 byte MAC(8 byte，last 2 byte not used)+Time(4byte)+Serial-No(4byte)

Type 2 byte Type will be introduced later

Flag 2 byte not used

Example,

offset data

0000 00 00 00 26 00 01 02 03 04 05 00 00 1f 5c b8 18

0010 00 00 00 06 00 01 00 00 00 01 00 01 31 35 30 38

0020 38 38 38 39 39 39 39 00 00 00 00 00 00 00 00 00

0030 00 00 00 00 00 08 00 31 00 32 00 33 00 34

00 00 00 26 length of body is 0x26

00 01 02 03 04 05 00 00 1f 5c b8 18 00 00 00 06

IS ID.

00 01 02 03 04 05 is MAC,

00 00 used to padding

1f 5c b8 18 is Time

00 00 00 06 is Serial-No

00 01 Message Type

00 00 Flag

3. SMS Connection

1. Make sure the configuration of DWG is correct. The SMS Server must listen to the

DWG. Once TCP connection is established, DWG will send userID and Password

Authentication message to SMS Server. SMS Server sends the response to userID and

Password message. If the userID and Password message is correct, DWG will send

Status message and Csq rssi message to SMS Server.

app:ds:correct

2. Every time the status of DWG changed, Status message is send to SMS Server

3. Status message

Type 0x07

Body is Variable,

Count of Ports 1 byte Determine how many record below

Port 0 1 byte 0, works

1, no SIM card inserted

2, not registered

3, unavailable

Port 1 1 byte The same as above

……

4. Response to Status message

SMS Server needs to send a response to Status message

Type 0x08

Body

Result 1 byte 0, succeed

1,fail

5. Example

offset data

0000 00 00 00 09 00 01 02 03 04 05 00 00 0d 2e 3f fd

0010 00 00 00 02 00 07 00 00 08 00 00 02 01 01 01 01

0020 01

00 00 00 09 Length of body is 9

00 01 02 03 04 05 MAC of DWG

00 07 Type is 0x07, it is a Status Message

08 Count of ports

00 00 work

02 not registered

01 01 01 01 01 no SIM card inserted

4. Keep alive

1. Keepalive message is sent by SMS Server first, and DWG will send back a keepalive

message. SMS server manages all connection stuff including the interval of sending

keepalive message and the strategy of disconnection.

2. Keepalive message

Type 0x00

Body is empty

3. Example

offset data

0000 00 00 00 00 00 01 02 03 04 05 00 00 0d 2e 3f ff

0010 00 00 00 03 00 00 00 00

00 00 00 00 Length is 0

00 00 Type is 0x00

5. Send SMS

1. SMS Server sends a Send SMS Request to DWG, DWG will give a response to that

request. After completing the process, DWG will send a Send SMS Result to SMS

Server. Also, SMS Server sends a response to that result.

2. Send SMS Request:

Type 0x01

Body

Port 1 byte 255 for any port

Encoding 1 byte 0, GSM 7bit

1, UNICODE

Type 1 byte 0,SMS

1,MMS(Not Implemented)

Count of Number 1 byte No more than 100

Number Characters, 24byte

Content Length 2 byte No more than 1530(gsm 7bit)

or 1340 (unicode)

SMS Content Characters

3. Response to Send SMS Reques:

Type 0x02

Body

Result 1 byte 0, succeed，

1, fail

2,timeout

3,bad request

4, port unavailable

5, partial succeed

255, other error

4. Send SMS Result

Type:0x03

Body

Count of Number 1 byte Determine how many record

below

Number 24 byte Characters

Port 1 byte


1, fail

2,timeout

3,bad request

4, port unavailable

5, partial succeed

255, other error

Count of slice 1 byte A long message will be sliced

to several SMS

Succeeded slices 1 byte

Ps: The length of this body is variable.

5. Response to Send SMS Result

Type：0x04

Body：


1, fail

6. Example

In this Example, A SMS is sent to15088889999 with message “1234”

offset data

0000 00 00 00 26 00 01 02 03 04 05 00 00 1f 5c b8 18

0010 00 00 00 06 00 01 00 00 00 01 00 01 31 35 30 38

0020 38 38 38 39 39 39 39 00 00 00 00 00 00 00 00 00

0030 00 00 00 00 00 08 00 31 00 32 00 33 00 34

00 00 00 26 length of Body

00 01 Type

00 port 0

01 UNICODE

00 SMS

31 35 30 38 38 38 38 39 39 39 39 Number 15088889999, 0 is for padding

00 08 Message length

00 31 00 32 00 33 00 34 1234 in Unicode encoding

Response from DWG

0000 00 00 00 01 00 01 02 03 04 05 00 00 1f 5c b8 18

0010 00 00 00 06 00 02 00 00 00

Send Result

0000 00 00 00 1d 00 01 02 03 04 05 00 00 1f 5c b8 18

0010 00 00 00 06 00 03 00 00 01 31 35 30 38 38 38 38

0020 39 39 39 39 00 00 00 00 00 00 00 00 00 00 00 00

0030 00 00 00 01 01

Response to Result

0000 00 00 00 01 00 01 02 03 04 05 00 00 1f 5c b8 18

0010 00 00 00 06 00 04 00 00 00

6. Receive SMS

1. DWG will send a Receive SMS Message to SMS Server Once DWG receive a SMS.

Type 0x05

Body

Number Characters，24 byte

Type 1 byte 0, SMS

1, MMS(Not Implemented)

Port 1 byte

Timestamp Characters，15 byte A string like 20010320210256

Time zone 1 byte -12 to +12

Encoding 1 byte 0, GSM 7BIT

1, UNICODE

Content length 2 byte

Content Characters

2. SMS send Response to Receive SMS Message

Type 0x06

Body


1, fail

Example

In this example, DWG received a SMS from 8615088889999 with content “abcd”

Receive SMS Message

0000 00 00 00 31 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 00 05 00 00 38 36 31 35 30 38 38 38

0020 38 39 39 39 39 00 00 00 00 00 00 00 00 00 00 00

0030 00 00 32 30 31 31 30 35 32 36 31 37 30 31 30 38

0040 00 08 00 00 04 61 62 63 64

00 00 00 31 Length of Body

00 05 Type

38 36 31 35 30 38 38 38 38 39 39 39 39 00 00 00 00 00 00 00 00 00 00 00

Number 8615088889999

32 30 31 31 30 35 32 36 31 37 30 31 30 38 00

Timestamp 2011.05.26. 17:01:08

00 Encoding is GSM 7BIT

00 04 Length of SMS is 4

61 62 63 64 Content is “abcd”

Response to Receive SMS Message

0000 00 00 00 01 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 00 06 00 00 00

7. Send USSD

1. Send USSD Request

Type 0x09

Body

Port 1 byte

Type 1 byte 1, Send

2, End session

Content length 2 byte

Content Characters Could be empty, ASCII

2. DWG sends a Response to Send USSD Request

Type 0x0A

Body


1, fail

2, timeout

3, bad request

4, port unavailable

255, other error

3. Example

Send USSD Request

0000 00 00 00 09 00 01 02 03 04 05 00 00 1f 5d 14 a7

0010 00 00 00 03 00 09 00 00 00 01 00 05 2a 31 30 30

0020 23

00 Port

01 Send USSD

00 05 Content length is 5

2a 31 30 30 23 Content is “*100#”

Response

0000 00 00 00 01 00 01 02 03 04 05 00 00 1f 5d 14 a7

0010 00 00 00 03 00 0a 00 00 00

8. Receive USSD

1. DWG will send a Receive USSD Message to SMS Server, once DWG receives a USSD.

Type 0x0B

body

Port 1 byte

Status 1 byte 0,No further user action required

1, Further user action required

2,USSD terminated by network

4, Operation not supported

Content Length 2 byte

Encoding 1 byte 1, UNICODE

Content Characters Could be empty

2. SMS Server sends a response to Receive USSD Message

Type 0x0C

body

result 1 byte 0, succeed

1, fail

Example

0000 00 00 00 76 00 01 02 03 04 05 00 00 0d 1f 96 b1

0010 00 00 00 06 00 0b 00 00 00 01 00 71 01 31 70 6f

0020 7b 3c 9a d8 9a d8 63 02 0a 32 57 28 7e bf 6e 38

0030 62 0f 0a 33 4e 0b 66 0e 66 1f 5e 94 75 28 8d 62

0040 49 50 41 44 0a 34 66 5a 95 f4 65 b0 95 fb 0a 35

0050 66 1f 5e a7 4e 13 53 3a 0a 36 72 31 57 28 6d f1

0060 72 31 65 f6 62 bd 8e ab 0a 37 80 a1 79 68 67 e5

0070 8b e2 0a 38 4f e9 5c 0f 7f 8e 59 73 4e 3a 62 11

0080 81 31 51 49 62 53 67 b6 0a 39 7f fb 98 75

00 from port 0

01 Fruther user action required means you can send more message follow by

the message

00 71 length is 0x71

01 Encoding is UNICODE

The following data is USSD content in UNICODE.

Response

0000 00 00 00 01 00 01 02 03 04 05 00 00 0d 1f 96 b1

0010 00 00 00 06 00 06 31 2d 00

9. Csq Rssi

1. Send Csq Rssi

Type 0x0D

Body is Variable

Count of Ports 1 byte Determine how many record below

Port 0 1 byte 0~31 csq rssi

99 unknown

Port 1 1 byte The same as above

……

2. Response to Csq Rssi

SMS Server needs to send a response to Csq Rssi

Type 0x0E

Body


1, fail

Example

offset data

0000 00 00 00 09 00 01 02 03 04 05 00 00 0d 2e 3f fd

0010 00 00 00 02 00 0d 00 00 08 63 07 01 0d 00 15 01 0c

0020 0a

00 00 00 09 Length of body is 9

00 01 02 03 04 05 MAC of DWG

00 0d Type is 0x0D, it is a csq rssi

08 Count of ports

63 Port 0 csq rssi is Unknown

07 01 0d 00 15 01 0c 0a Port 1~ Port 7 csq rssi

10. userID and Password Authentication

1. Send userID and Password Authentication

Type 0x0F

UserId Characters No more than 16 byte

Password Characters No more than 16 byte

2. Response to userID and Password Authentication

SMS Server needs to send a response to userID and Password Authentication

Type 0x10

Body


1, fail

Example

offset data

0000 00 00 00 20 00 01 02 03 04 05 00 00 0d 2e 3f fd

0010 00 00 00 02 00 0f 00 00 61 64 6D 69 6E 00 00 00

0020 00 00 00 00 00 00 00 00 61 64 6D 69 6E 00 00 00

0030 00 00 00 00 00 00 00 00

00 00 00 0a Length of body

00 01 02 03 04 05 MAC of DWG

00 0f Type is 0x0F, it is a userID and Password Authentication

61 64 6D 69 6E 00 00 00 00 00 00 00 00 00 00 00

userID

61 64 6D 69 6E 00 00 00 00 00 00 00 00 00 00 00

Password Authentication

11. RECEIVE SMS REPEICT

1. DWG will send a Receive SMS Receipt to SMS Server Once DWG receive a SMS

Receipt.

Type 0x11

Body

Port 1 byte

Number Characters，23 byte

Receipt ID 1 byte 0~255

Timestamp Characters，15 byte A string like 20010320210256

Time zone 1 byte -12 to +12

SMS report state 1 byte 0~31,Success

32~63,Temporary Error

64~95,Permanent Error

2. SMS send Response to Receive SMS Receipt

Type 0x12

Body


1, fail

Example

offset data

0000 00 00 00 2C 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 00 11 00 00 00 2B 38 36 31 35 30 38

0020 38 38 38 39 39 39 39 00 00 00 00 00 00 00 00 00

0030 57 32 30 31 31 30 35 32 36 31 37 30 31 30 38 00

0040 08 00 00 04 61 62 63 64

00 00 00 2C Length of body

00 11 Type

00 Port

2B 38 36 31 35 30 38 38 38 38 39 39 39 39 00 00 00 00 00 00 00 00 00

Number: +8615088889999

57 Receipt ID

32 30 31 31 30 35 32 36 31 37 30 31 30 38 00

Time 2011.05.26. 17:01:08

35 Time zone

00 SMS report state

Response

0000 00 00 00 01 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 00 12 00 00 00

12. SIM MESSAGE

1. SMS Server sends a sim message to DWG, DWG will give a response for the message

of the sim card.

sim message

Type 0x0101

Body

SlotNo 2 byte

2. Response to sim message

Type 0x0102

Body


1, fail

SlotNo 2 byte

Sim_State 1 byte 0, NONE

1, PIN

2, PUK

3, READY

4, WORKING

5, DISABLE

Iccid 25 byte

Imsi 16 byte

Example

offset data

0000 00 00 00 02 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 01 00 00 00 01

00 00 00 02 Length of body

01 01 Type

00 01 Slot

Response

0000 00 00 00 2B 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 02 00 00 00 00 01 01 38 36 31 35

0020 30 38 38 38 39 39 39 39 38 31 36 37 32 33 39 35

0030 00 00 00 00 32 30 31 31 30 35 32 36 31 37 30 31

0040 30 38 00

00 00 00 2B Length of body

01 01 Type

00 Result

00 01 Slot

01 Sim state

38 36 31 35 30 38 38 38 39 39 39 39 38 31 36 37 32 33 39 35 00 00 00 00

ICCID

32 30 31 31 30 35 32 36 31 37 30 31 30 38 00

IMSI

13. Unbind Port

1. SMS Server sends a unbind port to DWG, DWG will unbind the port. After completing

the process, DWG will give a response to that request.

unbind port

Type 0x0103

PortNo 2 byte 0~32

2. Response to unbind port

Type 0x0104

Body


1, fail

Example

offset data

0000 00 00 00 02 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 03 00 00 00 01


01 03 Type

00 01 Port

Response

0000 00 00 00 01 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 04 00 00 00

14. SWITCH SIMCARD

1. SMS Server sends a switch simcard to DWG, DWG will switch simcard. After

completing the process, DWG will give a response to that request.

switch simcard:

Type 0x0105

Body

Port 2 byte

Switched Slot 2 byte

2. Response to switch simcard:

Type 0x0106

Body


1, fail

Example

offset data

0000 00 00 00 04 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 05 00 00 00 01 00 12


01 05 Type

00 01 Port

00 12 Slot

Response

0000 00 00 00 01 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 06 00 00 00

15. RESET MODULE

1. SMS Server sends a reset module to DWG, DWG will reset the module. After


reset module:

Type 0x0107

Body

PortNo 2 byte

2. Response to restart simcard:

Type 0x0108

Body


1, fail

Example

offset data

0000 00 00 00 02 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 07 00 00 00 01


01 07 Type

00 01 Port

Response

0000 00 00 00 01 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 08 00 00 00

16. RESTART SIMBOX

1. SMS Server sends a restart simbox to DWG, DWG will restart simbox. After


restart simbox:

Type 0x0109

Body

Simbox No. 2 byte

2. Response to restart simbox:

Type 0x010A

Body


1, fail

Example

offset data

0000 00 00 00 02 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 09 00 00 00 01


01 09 Type

00 01 Simbox No.

Response

0000 00 00 00 01 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 0A 00 00 00

17. SIMBOX MESSAGE

1. SMS Server sends a simbox message to DWG, DWG will give a response for the

message of the simbox.

simbox message

Type 0x010B

Body

SIMBOX No. 2 byte

2. Response to simbox message

Type 0x010C

Body


1, fail

SIMBOX No. 2 byte

Simbox State 1 byte 0, INIT

2, CONNECTED

9, USED BY OTHER

Simbox version 32 byte

Simbox Mac 6 byte

Example

offset data

0000 00 00 00 02 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 0b 00 00 00 01


01 0b Type

00 01 Simbox No.

Response

0000 00 00 00 2A 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 0c 00 00 00 00 01 02 38 36 31 35

0020 30 38 38 38 39 39 39 39 38 31 36 37 32 33 39 35

0030 32 34 33 36 32 30 31 31 30 35 32 36 02 03 30 31

0040 30 38

00 00 00 2A Length of body

01 0c Type

00 Result

00 01 Simbox No.

02 Simbox state

38 36 31 35 30 38 38 38 39 39 39 39 38 31 36 37 32 33 39 35 32

34 33 36 32 30 31 31 30 35 32 36

Simbox version

02 03 30 31 30 38 Simbox 的 mac

18. OBTAIN IMEI

1. SMS Server sends a obtain IMEI to DWG, DWG will give a response for the message

of the IMEI.

obtain IMEI

Type 0x010D

PortNo 2 byte 0~31

2. Response to obtain IMEI

Type 0x010E

Body


1, fail

PortNo 2 byte 0~31

IMEI 15 byte

Example

offset data

0000 00 00 00 02 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 0d 00 00 00 01


01 0d Type

00 01 Port

Response

0000 00 00 00 12 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 0e 00 00 00 00 01 32 30 31 31 30 35

0020 32 36 31 37 30 31 30 38 32


01 0e Type

00 Result

00 01 Port

32 30 31 31 30 35 32 36 31 37 30 31 30 38 32

IMEI

19. MODIFY IMEI

1. API sends a modify imei to DWG, DWG will modify imei. After completing the process,

DWG will give a response to that request.

modify imei:

Type 0x010F

Body

Port 2 byte

IMEI 15 byte

2. Response to modify imei:

Type 0x0110

Body


1, fail

Example

offset data

0000 00 00 00 11 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 0f 00 00 00 01 32 30 31 31 30 35

0020 32 36 31 37 30 31 30 38 32


01 0f Type

00 01 Port

32 30 31 31 30 35 32 36 31 37 30 31 30 38 32

IMEI

Response

0000 00 00 00 01 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 10 00 00 00

20. PORT AND SLOT COUNT

1. SMS Server sends a port and Slot count to DWG, DWG will give a response for the

message

of port and slot count.

port and Slot count

Type 0x0111

2. Response to port and Slot count

Type 0x0112

Body

Port Count 2 byte 0~32

Slot Count 2 byte 0~128

Example

offset data

0000 00 00 00 00 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 11 00 00

01 11 Type

Response

0000 00 00 00 04 00 01 02 03 04 05 00 00 0d 2e 40 af

0010 00 00 00 2d 01 12 00 00 00 10 00 40


01 12 Type

00 10 port count

00 40 slot count

Appendix：

1. Message Type

Type Function Direction

0x00 Keepalive message DWG SMS Server

0x01 Send SMS Request SMS Server DWG

0x02 Response to Send SMS Request DWG SMS Server

0x03 Send SMS Result DWG SMS Server

0x04 Response to Send SMS Result SMS Server DWG

0x05 Receive SMS Message DWG SMS Server

0x06 Response to Receive SMS Message SMS Server DWG

0x07 Send SMS Request DWG SMS Server

0x08 Response to Send SMS Request SMS Server DWG

0x09 Send USSD Request SMS Server DWG

0x0A Response to Send USSD Request DWG SMS Server

0x0B Receive USSD Message DWG SMS Server

0x0C Response to Receive USSD Message SMS Server DWG

0x0D Send Csq Rssi DWG SMS Server

0x0E Response to Send Csq Rssi SMS Server DWG

0x0F Send userID and Password

Authentication

DWG SMS Server

0x10 Response to Send userID and Password

Authentication

SMS Server DWG

0x11 Receive SMS Receipt DWG SMS Server

0x12 Response to Receive SMS Receipt SMS Server DWG

0x0101 Receive SIM MESSAGE API Server DWG

0x0102 Send SIM MESSAGE DWG API Server

0x0103 Receive Unbind Port API Server DWG

0x0104 Response to Unbind Port DWG API Server

0x0105 Receive SWITCH SIMCARD API Server DWG

0x0106 Response to SWITCH SIMCARD DWG API Server

0x0107 Receive RESET MODULE API Server DWG

0x0108 Response to RESET MODULE DWG API Server

0x0109 Receive RESTART SIMBOX API Server DWG

0x010A Response to RESTART SIMBOX DWG API Server

0x010B Receive SIMBOX MESSAGE API Server DWG

0x010C Send SIMBOX MESSAGE DWG API Server

0x010D Receive Obtain IMEI API Server DWG

0x010E Response to Obtain IMEI DWG API Server

0x010F Receive MODIFY IMEI API Server DWG

0x0110 Response to MODIFY IMEI DWG API Server

0x0111 Receive PORT AND SLOT COUNT API Server DWG

0x0112 Send PORT AND SLOT COUNT DWG API Server

Documents

Dwg Sms API.v2.1 en.1