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

Using HTTP requests, you can send any command to the device and receive the response. The ZentriOS 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 a ZentriOS device include:

This demo uses the following ZentriOS features:

This example demonstrates how to:


To run this example follow these steps:

Connect Your Device to the Local Network

Since you'll need to configure the web server, the quickest way to setup the device is to use a ZentriOS 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 HTTP Server

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

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

Save the settings, then restart the network:


The device automatically starts the HTTP server on boot after connecting to the network.

The response from ZentriOS is similar to the following:

> Obtaining IPv4 address via DHCP
IPv4 address:
HTTP and REST API server listening on port: 80
[2015-01-15 | 23:48:42: Associated]

Note the reported device IPv4 address for later substition for <Device IP Address>.

Syntax of REST API ZentriOS Commands

The format of a REST API ZentriOS command GET request is: GET http://<Device IP Address>/command/<command>

For <Device IP Address> substitute the IP address reported by ZentriOS when the network came up.

For example, to issue the ver command: GET http://<Device IP Address>/command/ver

To issue a GET request from a browser, enter the URL http://<Device IP Address>/command/ver into the browser URL address box.

The format of a REST API ZentriOS command POST request is: POST http://<Device IP Address>/command/<command> followed immediately by a json formatted structure of the form:

   "flags"   : <flags>,
   "command" : "<ZentriOS 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 device), enter the following URL to retrieve the ZentriOS version string, or click the following link if this computer is connected to the same network as the device:

http://<Device IP Address>/command/ver

For <Device IP Address> substitute the IP address reported by ZentriOS when the network came up.

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

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

How does this work?

When the ZentriOS 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 device name. The operating system in your PC (or phone / tablet) translates the device name into the device IP address and sends the request to the device. On the device, 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 ZentriOS HTTP REST API, see Networking and Security, HTTP server with RESTful API.

Read a list of files on the device:

URL http://<Device IP Address>/command/ls
{"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 sys/kernel.bin\r\n# 5 215204 2.1.0 sys/services.bin\r\n# 6 38004 2.1.0 ZentriOS_webgui.css.gz\r\n# 7 1827 2.1.0 ZentriOS_webgui.html\r\n# 8 61492 2.1.0 ZentriOS_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 Zentri Mackerel eval board or Moray eval board:

URL http://<Device IP Address>/adc 7 (Mackerel - GPIO 7)
http://<Device IP Address>/adc 20 (Moray - GPIO 20)

Open a TCP connection to Google:

URL http://<Device IP Address>/command/tcp_client 80

Sending Commands Using JavaScript XMLHttpRequest

This demonstration uses POST requests. It is possible to send GET requests using XMLHttpRequest, but POST is more flexible. POST has no size restrictions, and the JSON data attribute allows additional data to be sent for ZentriOS commands such as file_create.

Download the demonstration HTML file js_rest_post.html.

This can be run directly as a file URL, provided you enable CORS for all domains on your device.

The following ZentriOS commands set up the device to work with the demonstration HTML page:

set wlan.ssid               <YOUR_SSID>
set wlan.passkey            <YOUR_PASSWORD>
set wlan.auto_join.enabled  1
set http.server.enabled     1
set http.server.cors_origin *

Run the HTML file in a browser with the JavaScript developed console displayed. This shows errors that cannot be caught and displayed with the JavaScript try and catch mechanism.

You can run any ZentriOS command from this HTML. Just edit the request fields and click the Send POST Request button.

The demonstration JavaScript assembles the POST JSON from the request fields and makes an XMLHttpRequest to send the command to the device and display the response.

View the HTML source to see the JavaScript. The core of the demonstration is the sendPost() function.

For higher level access to the HTTP RESTful API via JavaScript, see ZentriOS JavaScript API.

Sending Commands Using cURL

Curl, a command line URL utility, may also be used to connect to the ZentriOS 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 ZentriOS.

In some of the examples below, curl commands and response are shown in separate lines for readability purposes. Curl commands should be issued on a single command line.

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

ZentriOS Version

Curl Command
curl http://<Device IP Address>/command/version
ZentriOS Response
{"id":18,"code":0,"flags":0, "response":"ZentriOS-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 device 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 Command
curl -H "Content-Type: application/json" -d "{\"flags\":0,\"command\":\"ls -v\"}" http://<Device IP Address>/command
ZentriOS Response
{"id":3,"code":0,"flags":0, "response":"! # Type Flags Hnd Size Version Filename\r\n # 0 e-FB 0001 82 41741 command_help.csv\r\n # 1 e-FD 0001 53 135 default_setup.script\r\n # 2 e-FE 0001 81 1897 favicon.ico.gz\r\n # 3 e-03 0001 52 1236 geotrust_ca.pem\r\n # 4 i-00 801B 0 212736 sys/kernel.bin\r\n # 5 i-81 801B 52 215204 sys/services.bin\ r\n # 6 e-FE 0001 55 38004 ZentriOS_webgui.css.gz\r\n # 7 e-FE 0001 54 1827 ZentriOS_webgui.html\r\n # 8 e-FE 0001 65 61492 ZentriOS_webgui.js.gz\r\n # 9 e-01 0009 0 210412 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 ZentriOS file system:

Curl Command
curl -H "Content-type: application/json" -d "{\"flags\":0,\"command\":\"file_open default_setup.script\"}" http://<Device IP Address>/command
ZentriOS 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 Command
curl -H "Content-type: application/json" -d "{\"flags\":0,\"command\":\"stream_read 0 300\"}" <Device IP Address>/command
ZentriOS 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"}

Supporting ZentriOS Editions and Versions

Change Log

2015-04-28Added JavaScript XMLHttpRequest Section