HTTP API

Introduction

This page documents http endpoint that can be used to interact and configure the clock.

HTTP only

Currently, HTTPS is not supported as I yet have to figure a way to embed reliable ssl certificates (and a way to update them) in the device.

no security

Call to the api are not secured by any means. Anyone with access on the same network as the clock can access the api. It would be a bad1 idea to connect that clock on a network where untrusted people can join.

Configuration

Time zone

GET /zone?name=[zone]&host=[host]

If no parameters are given, the call return the current values in plain text.

Option Type Description
zone string optional name of the time zone to set. Example: Europe/Paris.
host string optional url of the Zone Transition server to use.

Network name

GET /network?name=[hostname]

Get and set the clock hostname.

If no parameters are given, the call returns the current hostname in plain text.

Option Type Description
hostname string optional hostname of the clock.

The hostname is used by the clock to presents itself on the network. Currently, it is used when registering to the dhcp and the mdns.

If triangle is the hostname of a clock, then it should be accessible at http://triangle.local/ from another device connected to the same network (if it manages mDNS (aka bonjour, zeroconf)).

Because network is not an immediate thing, when the name is changed, it might take some times to be effective.

Ping

GET /ping

Return the current configuration of the Ping system in a json format.

POST /ping

Params Values Description
enabled "true" or "false" optional enable or disable the ping system. Case sensitive.
url string optional url to ping (http only, https calls are not supported).
interval number optional interval between pings, in second. Minimum 60.

Available since 0.5

Information

GET /version

Get information about the firmware. It will return a message in JSON format: ex:

{ "version": "0.1", "type": "triangle"}

where:

  • version: is the version of the current firmware as set when it was built
  • type: the type of the clock

GET /uptime

Get the time elapsed since last reboot.

Available since 0.6

Display

POST /display

{ "strip": [ {"color": "#FF0000", "led": 0 }, {"color": "#00FF00", "led": 1 }, {"color": "#0000FF", "led": 3 } ], "duration": 2000 }

Where:

  • duration: the frame will be displayed for that amount of time in milliseconds.
  • strip: described the state of each led in the led strip.
    • color: the color as RGB in hexa
    • led: the number of the led

Note: if a led in the strip is not assigned to a color, it will be assigned to #000000.

This will put the given frame in a queue to be displayed on a first in first out base. Frame will be displayed for the given duration time, expressed in milliseconds.

Note: the size of the queue MAX_FRAMES is set in BaseClock/src/DisplayQueue.h.

Note: currently, the given frame will not be displayed as given. Each color will be added to the color that the display would have displayed otherwise.

GET /face/next

Use the next available face

Available since 0.4

GET /face/:id

Use a the specified face.

Where:

  • :id: integer, the id of the face to use.

Available since 0.4

  1. or a fun experiment? :) ↩