Device Discovery and HTTP RESTful API

This example uses the HTTP RESTful API to interact with the module using HTTP requests. Commands are sent to the module using HTTP REST methods such as GET and POST and a simple request syntax.

Using HTTP requests, you can send any command to the module and receive the response. The WiConnect Web App offers a full demonstration of the HTTP RESTful API. This application note demonstrates how to use the basic requests of the RESTful API.

Other ways of managing and interacting with an ACKme module include:

This demo uses the following WiConnect features:


This example demonstrates how to: - Setup the module to connect to your local network - Start the WiConnect mDNS service and HTTP web server - Use a web browser or cURL to send commands to the module, and receive responses from WiConnect


Setup

To run this example follow these steps:

Connect Your Module to the Local Network

Since you'll need to configure mDNS and the web server, the quickest way to setup the module is to use a WiConnect terminal - see Getting Started. Once you have a terminal connected, issue the following command to configure the credentials for the local network:

> network_up -s

Enable the mDNS and HTTP Server

Enable mDNS and specify the domain the module will respond to using the following commands:

set mdns.enabled 1
set mdns.name mymodule

Enable the WiConnect HTTP server and the RESTful API using the following WiConnect commands:

set http.server.enabled     1
set http.server.api_enabled 1

Save the settings, then restart the network:

save
network_down
network_up

The module automatically starts the mDNS discovery service and the HTTP server on boot after connecting to the network.

The response from WiConnect is similar to the following:

> Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.59
Starting mDNS
mDNS domain: mymodule.local
HTTP and REST API server listening on port: 80
[2015-01-15 | 23:48:42: Associated]

Syntax of REST API WiConnect Commands

The format of a REST API WiConnect command GET request is: GET http://mymodule.local/command/<command>

For example, to issue the ver command: GET http://mymodule.local/command/ver

To issue a GET request from a browser, enter the URL http://mymodule.local/command/ver into the browser URL address box.

The format of a REST API WiConnect command POST request is: POST http://mymodule.local/command/<command> followed immediately by a json formatted structure of the form:

{
   "flags"   : <flags>,
   "command" : "<wiconnect command>",
   "data"    : "<command data>"
}

The "data" value is required by commands that expect additional data sent immediately after the command, such as file_create. Some of the curl examples below demonstrate how to issue an HTTP POST request.

Sending Commands from a Web Browser

Using your favorite web browser (with a network client such as a PC, phone or tablet connected to the same local network as the module), enter the following URL to retrieve the WiConnect version string, or click the following link ver if this computer is connected to the same network as the module:

The browser responds with the WiConnect version embedded in a JSON object, similar to the following text.

{"id":18,"code":0,"flags":0,"response":"WiConnect-2.1.0.0, Built:2015-01-15 ... }

Troubleshooting

If you are having problems making this work, try the following


How does this work?

When the WiConnect command is entered into the web browser address box, the browser translates the URL into an HTTP GET request and sends the request to the module name. The operating system in your PC (or phone / tablet) translates the module name into the module IP address and sends the request to the module. On the module, the HTTP web server receives and processes the request, and then provides a response back to the server.

A few more examples are shown below. For full documentation on the WiConnect HTTP REST API, see Networking & Security, WiConnect REST API.

Read a list of files on the module:

URLhttp://mymodule.local/command/ls
WiConnect
Response
{"id":2,"code":0,"flags":0,"response":"! # Size Version Filename\r\n# 0 41741 2.1.0 command_help.csv\r\n# 1 135 2.1.0 default_setup.script\r\n# 2 1897 2.1.0 favicon.ico.gz\r\n# 3 1236 2.1.0 geotrust_ca.pem\r\n# 4 212736 2.1.0 upgrade_app.exe\r\n# 5 215204 2.1.0 wiconnect.exe\r\n# 6 38004 2.1.0 wiconnect_webgui.css.gz\r\n# 7 1827 2.1.0 wiconnect_webgui.html\r\n# 8 61492 2.1.0 wiconnect_webgui.js.gz\r\n# 9 210412 5.26.230 wifi_fw.bin\r\n"}

Read the raw value of the ADC connected to the thermistor on the ACKme Mackerel eval board or Moray eval board:

URLhttp://mymodule.local/adc 7 (Mackerel - GPIO 7)
http://mymodule.local/adc 20 (Moray - GPIO 20)
WiConnect
Response
{"id":104,"code":0,"flags":0,"response":"0x835\r\n"}

Open a TCP connection to Google:

URLhttp://mymodule/command/tcp_client google.com 80
WiConnect
Response
{"id":4,"code":0,"flags":0,"response":"0\r\n"}

Read the response to the TCP client connection above:

URLhttp://mymodule.local/log
WiConnect
Response
{"logs":["HTTP and REST API server listening on port: 80","[2015-01-15 - 01:09:23: Associated]\r\n> ","Resolving host: google.com","[2015-01-15 - 01:28:53: Opening: google.com:80]","Connecting (TCP): 216.58.220.142:80","[2015-01-15 - 01:28:54: Opened: 0]"]}

Using cURL

Curl, a command line URL utility, may also be used to connect to the WiConnect webserver. Curl is typically run from a PC or Linux command line for transferring data with a URL syntax. The following examples show how to use cURL with WiConnect.

In some cases, the arguments to curl in the examples below have been put onto separate lines for readability purposes only. Curl commands should be issued on a single command line.

Tip! If you are having trouble using curl, try using the -v verbose flag.

WiConnect Version

Curl
$> curl http://mymodule.local/command/version

|

WiConnect
Response
{"id":18,"code":0,"flags":0,"response":"WiConnect-2.1.x.x, Built:2015-01-14 21:34:43 for AMW004.3, Board:AMW004-E03.3" }

Curl used with a URL only issues an HTTP GET request.

Verbose file list

This example reads a verbose list of files on the module and uses the more sophisticated POST request API. Note that the double-quotes may need to be escaped with backslash characters (as shown below) on some operating systems, such as Windows.

Curl used with the -d (--data) option issues an HTTP POST request. Note that the Content-Type header must be supplied to specify that the data posted is in json format.

Curl
$> curl -H "Content-Type: application/json"
        -d "{\"flags\":0,\"command\":\"ls -v\"}"
        http://mymodule.local/command

|

WiConnect
Response
{"id":3,"code":0,"flags":0,"response":"! # Type Flags Hnd Size Version Filename\r\n# 0 e-FB 0001 82 41741 2.1.0.0 command_help.csv\r\n# 1 e-FD 0001 53 135 2.1.0.0 default_setup.script\r\n# 2 e-FE 0001 81 1897 2.1.0.0 favicon.ico.gz\r\n# 3 e-03 0001 52 1236 2.1.0.0 geotrust_ca.pem\r\n# 4 i-00 801B 0 212736 2.1.0.0 upgrade_app.exe\r\n# 5 i-81 801B 52 215204 2.1.0.0 wiconnect.exe\ r\n# 6 e-FE 0001 55 38004 2.1.0.0 wiconnect_webgui.css.gz\r\n# 7 e-FE 0001 54 1827 2.1.0.0 wiconnect_webgui.html\r\n# 8 e-FE 0001 65 61492 2.1.0.0 wiconnect_webgui.js.gz\r\n# 9 e-01 0009 0 210412 5.26.230.12 wifi_fw.bin\r\n"}

The value of the response key is the return data from the command. In this case it is the list of files. This is formatted to be read on a terminal in a monospace font, with new lines where each \r\n character sequence appears.

Open and Read a file

Open the default_setup.script file located on the WiConnect file system:

Curl
$> curl -H "Content-type: application/json"
        -d "{\"flags\":0,\"command\":\"file_open default_setup.script\"}"
        http://mymodule.local/command

|

WiConnect
Response
{"id":14,"code":0,"flags":0,"response":"0\r\n"}

The value of the response key is the return data from the command. In this case it is the stream number for the open file stream, 0, which is used as an argument to the stream_read command issued below.

Read the file using the stream_read command:

Curl
$> curl -H "Content-type: application/json"
        -d "{\"flags\":0,\"command\":\"stream_read 0 300\"}"
        mymodule.local/command

|

WiConnect
Response
{"id":15,"code":0,"flags":0,"response":"network_up,-s ,Configuration network credentials\r\nset wlan.auto_join.enabled,true,Enable network auto-join\r\nsave,-,Saving settings\r\n\r\n"}

Change Log

ModifiedChangesWiConnect Version
Required
2015-02-03Created2.1+