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 bytelast 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.

2. Every time the status of DWG changed, Status messageis 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
Result 1 byte 0, succeed
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
Type0x04
Body
Result 1 byte 0, succeed
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 Characters24 byte
Type 1 byte 0, SMS
1, MMS(Not Implemented)
Port 1 byte
Timestamp Characters15 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
Result 1 byte 0, succeed
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
Result 1 byte 0, succeed
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 Messageto 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
result 1 byte 0, succeed
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 userI D 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
result 1 byte 0, succeed
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 Characters23 byte
Receipt ID 1 byte 0~255
Timestamp Characters15 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
Result 1 byte 0, succeed
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 messageto 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
Result 1 byte 0, succeed
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
Result 1 byte 0, succeed
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

00 00 00 02 Length of body
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
Result 1 byte 0, succeed
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

00 00 00 04 Length of body
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
completing the process, DWG will give a response to that request.
reset module:
Type 0x0107
Body
PortNo 2 byte

2. Response to restart simcard:
Type 0x0108
Body
Result 1 byte 0, succeed
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

00 00 00 02 Length of body
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
completing the process, DWG will give a response to that request.
restart simbox:
Type 0x0109
Body
Simbox No. 2 byte

2. Response to restart simbox:
Type 0x010A
Body
Result 1 byte 0, succeed
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

00 00 00 02 Length of body
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
Result 1 byte 0, succeed
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

00 00 00 02 Length of body
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
Result 1 byte 0, succeed
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

00 00 00 02 Length of body
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

00 00 00 12 Length of body
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
Result 1 byte 0, succeed
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

00 00 00 11 Length of body
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

00 00 00 04 Length of body
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