SDK

Overview

Language
C, compiled to WebAssembly
Memory
64 KB per app
Numbers
Integers only, no floating point
Package
app.wasm, manifest.json, translations, pictures, files

Getting started

  1. Install the toolchain

    wasi-sdk, Java, git.

    shell
    git clone https://github.com/GrakovNe/perinkpheral.git
    cd perinkpheral
    export WASI_SDK_PATH=$HOME/opt/wasi-sdk
    tools/perinkpheral
  2. Create an application

    shell
    tools/perinkpheral new ../myapp --title "My App"
  3. Build

    shell
    tools/perinkpheral build ../myapp --out ../myapp/build
  4. Run in the simulator

    shell
    tools/perinkpheral sim ../myapp
  5. Run on the device

    shell
    export PERINKPHERAL_HOST=perinkpheral-xxxx.local
    tools/perinkpheral run ../myapp --shot screen.png
    tools/perinkpheral press 2 2 --shot pressed.png
    tools/perinkpheral log --follow

Example

hello.c
#include "app_text.h"
#include "host_api.h"

static const char PRESSES_KEY[] = "presses";
static int32_t presses;

void app_init(void)
{
    /* Restore state: the host unloads the application
     * when it leaves the screen. */
    kv_get(PRESSES_KEY, sizeof PRESSES_KEY - 1, &presses, sizeof presses);
}

void app_on_terminate(void)
{
    kv_set(PRESSES_KEY, sizeof PRESSES_KEY - 1, &presses, sizeof presses);
}

void app_on_button(int32_t event)
{
    if (event == BTN_OK_PRESSED) {
        presses++;
        request_redraw(HOST_REDRAW_NORMAL);
    }
}

void app_on_draw(void)
{
    char line[32];
    app_text_t text;
    app_text_start(&text, line, sizeof line);
    app_text_add(&text, "Presses: ");
    app_text_add_number(&text, presses);

    gfx_text(HOST_UI_MARGIN, HOST_UI_MARGIN, HOST_FONT_TEXT, "Hello from wasm", 15);
    gfx_text(HOST_UI_MARGIN, 60, HOST_FONT_TEXT, line, app_text_length(line));
}

The manifest

manifest.json
{
  "name": "weather",
  "title": "Weather",
  "version": "0.2.5",
  "abi": 2,
  "settings": [
    { "key": "city", "type": "place", "title": "City",
      "latitude": "lat", "longitude": "lon" },
    { "key": "lat", "type": "number", "title": "Latitude" },
    { "key": "lon", "type": "number", "title": "Longitude" },
    { "key": "every", "type": "choice", "title": "Update interval",
      "options": ["15 min", "30 min", "1 hour", "3 hours"] }
  ],
  "polls": [
    {
      "url": "https://api.open-meteo.com/v1/forecast?latitude={{lat}}&longitude={{lon}}&current=temperature_2m,weather_code",
      "every": "{{every}}",
      "pick": ["current.temperature_2m", "current.weather_code"]
    }
  ]
}
KeyMeaning
nameUnique id: 1-13 characters, a-z, 0-9, - and _
titleName in the menu, up to 23 characters
pollsWeb requests the device makes on a schedule, up to 4
hostsServers the app may contact
settingsUp to 8. Types: text, secret, number, choice, toggle, place, url, link, list
intentsSystem events to receive: device start, clock change, network back
icon11 x 11 pixel icon: # black, . white
fullscreenUse the whole screen, without the top bar
writes_filesThe app saves files; 32 KB are reserved for it
systemAccess to device settings, clock and apps; the user confirms on install
certificatesCertificates for servers that browsers do not trust
companionA web page that helps the user set the app up
firmwareThe oldest firmware the app runs on; the build works it out from the calls it makes

Handlers and state

FunctionCalled when
app_init()The app starts
app_on_focus() / app_on_blur()The app appears on screen or leaves it
app_on_terminate()The app is about to close: save state here
app_on_button(event)A button is pressed, released, or held
app_on_back()BACK is pressed, for apps with several pages
app_on_draw()The screen needs drawing
app_on_timer(id)A timer fired, while the app is on screen
app_on_alarm(id)An alarm fired, even if the app is closed
app_on_values(poll, status)Scheduled data arrived, already parsed
app_on_data(...)A piece of a response arrived
app_on_settings()The user changed the settings
app_on_intent(type)A system event the app asked for
app_on_installed() / app_on_updated()First start after install or update

Buttons and state

Buttons
1 up, 2 OK, 3 down, 4 back; hold BACK for the menu
Saved data
kv_set(), kv_get()

Network data

On a schedule
Requests in the manifest
On demand
http_request() from the code
Ready values
List JSON paths in "pick": app_on_values() gets the values
Raw response
Without "pick": app_on_data() gets the response piece by piece
Show on screen
request_focus() opens the app when its data arrives
weather.c
void app_on_values(int32_t poll, int32_t http_status)
{
    /* Values of the "pick" paths, in order. 1 decimal: tenths. */
    int32_t temperature, code;
    if (http_status == 200 &&
        app_value_number(0, 1, &temperature) &&
        app_value_number(1, 0, &code)) {
        state.temperature = temperature;
        state.code = code;
        app_state_save("state", &state, sizeof state);
        request_redraw(HOST_REDRAW_NORMAL);
    }
}

Graphics and UI kit

PartFunctions
Text in four stylesui_text, ui_text_lines, ui_title
List with scroll barui_list_row, ui_list_visible
Dialog: text, icon, buttonsui_notice
Tile: name, picture, valueui_cell, ui_cell_fit
Chart: line, area, bars, stepsui_chart
Value with unitui_value
Choice of a value, date and timeui_picker, ui_date
Message while there is nothing to showui_reason

Limits

WhatLimit
App size48 KB
Memory64 KB
Time per call3 s
Saved data2 KB, up to 1 KB per value
Files64 KB in the package; 32 KB if the app writes files
Scheduled requests4, every 10 s to 1 day
Requests at once16
Response size256 KB parsed, 4 MB piece by piece
Settings8, values up to 255 bytes
Timers and alarms4 and 4
Apps on a deviceUp to 24, while there is space

Tools

CommandDescription
new <dir>Start a new app
build <app> --out <dir>Build and check
sim <app>Run in the simulator
run <app>Run on the device
serve [app]A page with the device screen, buttons and log
shot / press / openScreenshot, press buttons, open an app
log [--follow]Device log
set <app> <key> <value>Change an app setting
catalog <folder> --out <dir>Build a catalog
strings export / importTranslations as a spreadsheet
flash [image]Update the firmware over Wi-Fi
usb <port>Control a device over USB

CLion plugin

Runs on
Device, simulator (macOS, Linux)
Includes
Toolchain setup, live device screen, manifest checks, firmware upload

Publishing

shell
tools/perinkpheral catalog apps --out catalog

Reference