BLOCKCLOCK mini “Push” API

This document describes the PUSH API for sending data to the BLOCKCLOCK mini. In normal operation, out of the box, the BLOCKCLOCK mini uses a completely different “pull” protocol to get and display values.

All API endpoints start with /api
Only http (not https) is supported.
You must be on the same LAN as the BLOCKCLOCK.
You may need to provide the password using HTTP digest authentication, as follows: curl --digest -u :PASSWORD but if you have not set a password, then this isn’t needed.
All responses are JSON, including errors, except for 404 errors that may be HTML.

Quick Examples

These examples assume your BLOCKCLOCK mini is using IP address: 10.0.0.104

% curl "http://10.0.0.104/api/pick/cm.markets.price"

% curl "http://10.0.0.104/api/show/text/Hello"

% curl "http://10.0.0.104/api/show/number/12999?pair=USD/BTC&sym=bitcoin"

% curl --digest -u :PASSWORD "http://10.0.0.104/api/status"
{
    "tags": [
        "binance.BTCBUSD.ask",
        "binance.BTCBUSD.bid",
        "binance.BTCUSDC.ask",
        "aqua.BTC-USD.bid",
        ...
    ],
    "version": "0.2.1",
    "rendered": {
        "number": 8261.1,
        "pair": [
            "BTC",
            "GBP"
        ],
        "tl_text": "Coinbase BTC-GBP Spot",
        "label": "Coinbase BTC-GBP Spot",
        "contents": [
            "/BTC/GBP",
            "\u00a3",
            "8",
            "2",
            "6",
            "1",
            "/.10"
        ],
        "string": null,
        "br_text": null,
        "is_error": false,
        "tag": "coinbase.BTC-GBP.spot"
    },
    "menu_active": false
}

Displaying Your Custom Data

When your program sends data to the BLOCKCLOCK mini using this API, it is displayed immediately. When the clock would normally update your API data will be replaced (top of the next 5 minute interval or less often). Set the update rate to “manual” if you want to exclusively push data to it.

Displaying Numbers

To show a numeric value, use /api/show/number/N where N is the number to show.
It will be right justified into the seven available digits.
If you find the mini does not render your number correctly, it’s probably better to render as you wish, and then send as text.

Displaying Text

To show a text value (which could be pre-formated numeric digits), use /api/show/text/FOO where FOO is the text to show.
It will be right padded into the seven available digits.
Extra characters will trimmed from the left side, if it’s too long.
Dot and comma can combine with left-adjacent character, so strings like “1,234,567” can be displayed even though they are longer than 7 characters because “1,” and “4,” will be shown in a single position.

Decoration

You may add query string arguments to either of those urls to change how the value is shown:

add tl=Text message to add tiny text to top left
add br=Text message to add tiny text to bottom right
add pair=ABC/DEF to replace the left most digit with ABC / DEF (a currency pair, typically)
- limited to upper case letters, numbers and a few symbols
- max 4 characters over 4 characters
- omit the slash, to show a single 1-4 letter code (top line)
add sym=$ to insert the indicated symbol, when space is available left of the number. In addition to single-letter currency codes, the special values “bitcoin”, “litecoin”, “USD” will show those logos or dollar sign ($) respectively.

Arbitrary Displays

We are planning to expand this API to allow arbitrary images and messages (in all the fonts) to be displayed.

Rate Limiting

Because of the limited update rate of the EInk displays, you should only update the display every five minutes and no more frequently. If you exceed a rate of once per minute, your program will receive a 429 error and a message about required delay.

Read Display

You can get currently displayed value, and other status information, using: /api/status

For example:

% curl --digest -u :PASSWORD "http://10.0.0.104/api/status"
{
    "tags": [
        "datetime.world.a",
        "datetime.world.b",
        "electrum.BTC.block_height",
        "coinbase.BTC-GBP.spot",
        "bylls.sell.price",
        "cm.markets.price"
    ],
    "showing": "coinbase.BTC-GBP.spot",
    "version": "0.2.1",
    "rendered": {
        "number": 8261.1,
        "pair": [
            "BTC",
            "GBP"
        ],
        "tl_text": "Coinbase BTC-GBP Spot",
        "label": "Coinbase BTC-GBP Spot",
        "contents": [
            "/BTC/GBP",
            "\u00a3",
            "8",
            "2",
            "6",
            "1",
            "/.10"
        ],
        "string": null,
        "br_text": null,
        "is_error": false,
        "tag": "coinbase.BTC-GBP.spot"
    },
    "menu_active": false
}

The values are defined as follows:

tags: list of tags defined by user to be shown
version: firmware version currently running
rendered: current contents of the screen
menu_active: a menu is being shown (vs. data)
showing: which tag, is currently being displayed

Show Specific Data From Backend

/api/pick/next - move the next data tag in programmed sequence

/api/pick/cm.markets.price - display the indicated tag (it need not be in your list already) - can fail with 404 if unknown/undefined tag (display is affected)

/api/pick/redraw - redraw the current tag - good means to recover from a failed /api/pick/bad.tag

Other functions over API

These endpoints perform immediate functions:

/api/action/pause
- turn off updates (manual updates only)
/api/action/update
/api/action/update?rate=60
- go to 5 minute updates, or 60 minutes, etc
- this undoes the effect of “pause” command
/api/action/clear_menu
- cancel menu being shown, if any is active
- restores normal data-display operation
/api/action/reboot
- reboot system
/api/action/powerdown
- power down (further API access is not possible)
/api/lights/RRGGBBWW
/api/lights/RGBW
/api/lights/RGB
/api/lights/off
- control the lights, with immediate effect
- takes hex value, like a web page, without hash prefix
/api/lights/flash
- do the animation configured for when value changes normally
/api/image/{0..6}/{image name}
- show an image in specific digit from left (0) to right (6)
- images may include (subject to change): ‘bitcoin’, ‘litecoin’, ‘bar’, ‘od_wordmark’, ‘register’, ‘honey’
/api/ou_text/{0..6}/{over}/{under}
- show over/under text in indicated position
- max 4 chars each (sometimes 5 if they are narrow)