Add an HTTP device

The HTTP driver reaches devices that answer HTTP requests with JSON, and stream live values as server-sent events. One HTTP definition can serve many devices of the same kind, each with its own base URL.

You need a running, registered bridge. See Install and register a bridge.

Install the definition

Write a definition for the kind of device, or use one you have. See Write a definition. Install it on the bridge:

nodelets definition install heater.json

A definition takes effect at once, with no restart and no request to the device. Installing the same file again changes nothing. Installing a different file with an ID that is already installed fails with A different definition with this ID is already installed: give a changed definition a new id.

Add the device

The bridge must be connected to the cloud. Run:

nodelets thing add

Answer the questions:

Question	What to enter
Definition	The list number or the definition’s ID
Name	The name people see, for example Workshop heater
Base URL	The device’s origin, for example http://10.0.4.21 or https://10.0.4.21:8443
Add HTTP headers?	y to add headers sent with every request, such as a device token

The base URL is a scheme, host and optional port, with no path. Binding paths in the definition are added to it. HTTPS uses normal certificate checks, and the driver follows no redirects.

The command prints the new Thing’s ID, which is also its Nodelet ID. The base URL and headers stay on the bridge. nodelets thing show ID lists header names and never their values.

The device does not have to answer when you add it. A device that is off is added all the same, and until it is back, calls to it fail with an error such as THING_UNAVAILABLE or TIMEOUT.

Check it

nodelets thing list
nodelets thing show nl_5c0e8a2f-7d41-4b9e-a3c6-2f8d1e4b7a90

thing show lists each property, action and event with what it can do. Neither command contacts the device. The Setup column reads active once the cloud has acknowledged the Thing, and pending until then.

On the dashboard, reload the Bridges page to see the new Nodelet as a card.

Change the address or the definition

nodelets thing update nl_5c0e8a2f-7d41-4b9e-a3c6-2f8d1e4b7a90

thing update asks the same questions as thing add and replaces the Thing’s definition and settings. The Nodelet keeps its ID. A change of definition ends any live subscription to it, and the subscriber is told why.

When an add is interrupted

If the connection drops while a Thing is being added or changed, the Thing keeps its ID and shows pending. The bridge publishes it again when it next connects. For a new Thing, the next thing add also asks whether to publish it now, and thing update ID does the same for a changed one.

Limits

• Each operation is one HTTP request with a deadline of 10 seconds. Nothing is retried.
• A response may be at most 256 KiB.
• Reads use GET. Writes use PUT, POST or PATCH and send the value as the JSON body. Actions use POST.
• A status outside 200 to 299 is DEVICE_ERROR with outcome not-executed.

See Outcomes and errors for every result.