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.