Extended Socket example: Single HTTP Connection

This example demonstrates a complete request with an HTTP server. It fetches a random fact about a number from a web services API offered by the website http://numbersapi.com.

Note Digi is not affiliated with numbersapi.com and the example is for education only.

Send a Socket Create frame

Note To adapt this example for an HTTPS server, change Protocol below to 0x04 (TLS) and optionally use the Socket Option frame to specify a TLS profile.

Field Value
Frame type

0x40 (Socket Create)

Frame ID 0x01
Protocol 0x01 (TCP)

Socket Create frame data:

7E 00 03 40 01 01 BD

Receive a Socket Create response

The XBee responds to the Socket Create request with a response. The response contains the socket ID assigned. In this example, the socket ID is 0.

Field Value
Frame type

0xC0 (Socket Create Response)

Frame ID 0x01
Socket ID 0x00
Status 0x00 (Success)

Socket Create Response received from XBee:

7E 00 04 C0 01 00 00 3E

Send Socket Connect

This examples uses the "string" destination address type to have the XBee perform DNS look-up during the connection process.

Note To adapt this example for TLS, use destination port 0x01 0xbb (decimal 443). Be aware that many HTTPS servers use SNI (Server Name Identification) which is not currently supported.

Field Value
Frame type

0x42 (Socket Create Response)

Frame ID 0x01
Socket ID 0x00
Destination Port 0x00 0x50 (80 decimal, HTTP)
Destination Address Type 0x01 (String)
Destination Address numbersapi.com

Socket Connect frame data:

7E 00 14 42 01 00 00 50 01 6E 75 6D 62 65 72 73 61 70 69 2E 63 6F 6D C8

Receive a Socket Connect Response

The request to connect is immediately acknowledged with a response. However, it is not permitted to proceed transmitting data until the next stage, after a Socket Status frame has been received indicating success.

Field Value
Frame type

0xC2 (Socket Connect Response)

Frame ID 0x01
Socket ID 0x00
Status 0x00 (Success)

Socket Connect Response received from XBee:

7E 00 04 C2 01 00 00 3C

Receive a Socket Status

The socket has been fully established when a Socket Status frame is received with the connected status after the socket has connected.

Field Value
Frame type

0xCF (Socket Status)

Socket ID 0x00
Status 0x00 (Connected)

Socket Status received from XBee with connected status:

7E 00 03 CF 00 00 30

Send HTTP Request using Socket Send frame

The request uses the "Connection: close" header to have the server close the connection on request completion. This allows the example to demonstrate the Socket Status reporting of a close by the peer.

Field Value
Frame type

0x44 (Socket Status)

Frame ID 0x01
Socket ID 0x00
Transmit Options 0x00
Data

GET /random/trivia HTTP/1.1

Host: numbersapi.com

Connection: close

Socket Send frame data:

7E 00 4C 44 01 00 00 47 45 54 20 2F 72 61 6E 64 6F 6D 2F 74 72 69 76 69 61 20 48 54 54 50 2F 31 2E 31 0D 0A 48 6F 73 74 3A 20 6E 75 6D 62 65 72 73 61 70 69 2E 63 6F 6D 0D 0A 43 6F 6E 6E 65 63 74 69 6F 6E 3A 20 63 6C 6F 73 65 0D 0A 0D 0A B6

Receive TX Status

Extended sockets use the existing TX Status frame (0x89) to report acceptance of the data for transmit.

Field Value
Frame type

0x89 (TX Status)

Frame ID 0x01
Status 0x00 (Success)

TX Status received from XBee data:

7E 00 03 89 01 00 75

Receive one or more Receive Data frames

The server will respond with an interesting fact about a number. The following information is a sample response. Multiple frames may be needed to contain the full response content depending on size and network conditions.

Field Value
Frame type

0xCD (Socket Receive)

Frame ID 0x00
Socket ID 0x00
Status 0x00
Payload

HTTP/1.1 200 OK

Server: nginx/1.4.6 (Ubuntu)

Date: Thu, 18 Jul 2019 16:13:47 GMT

Content-Type: text/plain; charset="UTF-8"; charset=utf-8

Content-Length: 53

Connection: close

X-Powered-By: Express

Access-Control-Allow-Origin: *

Access-Control-Allow-Headers: X-Requested-With

X-Numbers-API-Number: 270

X-Numbers-API-Type: trivia

Pragma: no-cache

Cache-Control: no-cache

Expires: 0

 

270 is the average number of days in human pregnancy.

Receive Data received from XBee containing web service response:

7E 01 C5 CD 00 00 00 48 54 54 50 2F 31 2E 31 20 32 30 30 20 4F 4B 0D 0A 53 65 72 76 65 72 3A 20 6E 67 69 6E 78 2F 31 2E 34 2E 36 20 28 55 62 75 6E 74 75 29 0D 0A 44 61 74 65 3A 20 54 68 75 2C 20 31 38 20 4A 75 6C 20 32 30 31 39 20 31 36 3A 31 33 3A 34 37 20 47 4D 54 0D 0A 43 6F 6E 74 65 6E 74 2D 54 79 70 65 3A 20 74 65 78 74 2F 70 6C 61 69 6E 3B 20 63 68 61 72 73 65 74 3D 22 55 54 46 2D 38 22 3B 20 63 68 61 72 73 65 74 3D 75 74 66 2D 38 0D 0A 43 6F 6E 74 65 6E 74 2D 4C 65 6E 67 74 68 3A 20 35 33 0D 0A 43 6F 6E 6E 65 63 74 69 6F 6E 3A 20 63 6C 6F 73 65 0D 0A 58 2D 50 6F 77 65 72 65 64 2D 42 79 3A 20 45 78 70 72 65 73 73 0D 0A 41 63 63 65 73 73 2D 43 6F 6E 74 72 6F 6C 2D 41 6C 6C 6F 77 2D 4F 72 69 67 69 6E 3A 20 2A 0D 0A 41 63 63 65 73 73 2D 43 6F 6E 74 72 6F 6C 2D 41 6C 6C 6F 77 2D 48 65 61 64 65 72 73 3A 20 58 2D 52 65 71 75 65 73 74 65 64 2D 57 69 74 68 0D 0A 58 2D 4E 75 6D 62 65 72 73 2D 41 50 49 2D 4E 75 6D 62 65 72 3A 20 32 37 30 0D 0A 58 2D 4E 75 6D 62 65 72 73 2D 41 50 49 2D 54 79 70 65 3A 20 74 72 69 76 69 61 0D 0A 50 72 61 67 6D 61 3A 20 6E 6F 2D 63 61 63 68 65 0D 0A 43 61 63 68 65 2D 43 6F 6E 74 72 6F 6C 3A 20 6E 6F 2D 63 61 63 68 65 0D 0A 45 78 70 69 72 65 73 3A 20 30 0D 0A 0D 0A 32 37 30 20 69 73 20 74 68 65 20 61 76 65 72 61 67 65 20 6E 75 6D 62 65 72 20 6F 66 20 64 61 79 73 20 69 6E 20 68 75 6D 61 6E 20 70 72 65 67 6E 61 6E 63 79 2E 8B

Receive Socket Status indicating closed connection

Finally, due to the "Connection" header in the request, the server should remotely close the connection.

Field Value
Frame type

0xCF (TX Status)

Socket ID 0x00
Status 0x07 (Connection lost)

Example Socket Status received from XBee indicating connection lost:

7E 00 03 CF 00 07 29

When Socket Status indicating a connection close is received, the socket ID will have been de-allocated by the XBee and no further operations are possible or necessary using that ID.