Headless Development

Now we have the toolchain installed, a microcontroller running some example code - lets build a headless application to control the hardware!

Headless templates are a recent addition and the quickstart guide is being actively improved.

Feel free to contact us if something doesn't make sense or you need extra help!

Starting with the template

From the command-line, run arc init hello-headless --template node to populate the template in a new folder called hello-headless.

This bootstraps a new project - follow the prompts to enter the human-readable product name e.g. Harmonica Test-Jig Controller. The the required dependencies will be downloaded and prepared for use.

Navigate to the hello-headless folder in your terminal, then run arc start. It will run through a quick process of manually controlling the hello-blink enabled LED.

◼ EUI000: Connected to device completed in 0s 678ms
◼ EUI000: Found and connected to 50018
◼ EUI002: name: HelloEUI
◼ EUI000: ┌ LED Sweep
◼ EUI002: │ led switched after 30ms, state is 0
◼ EUI002: │ led switched after 40ms, state is 0
◼ EUI002: │ led switched after 50ms, state is 0
[...]
◼ EUI000: LED Sweep completed in 4s 504ms
◼ EUI000: Tests complete
◼ EUI000: Done in 5s 209ms

Editing the template

Open the arc generated project folder hello-headless with your IDE/text editor of preference. We strongly recommend VS Code, as the real-time Typescript hinting and integration works wonderfully.

Connecting to hardware

Unlike the graphical template which auto-detects and displays a connection card for your hardware, handling hardware with a CLI tool is a bit more involved.

The template demonstrates finding any valid device and connecting to it, with some simple timeout and error handling.

// hello-headless/src/tests/blink-test.ts
// See lines 27-57, TODO explanation

Displaying text

For CLI use, the most relevant output method is printing strings to stdout.

The template describes some basic types of log output, UNAMED, EXCEPTION and TRANSIENT, and these are used with reportInfo() .

The template uses TRANSIENT to print to an area that's allowed to be overwritten as newer content is printed or when the next section of the program begins.

report.reportInfo(
  LogMessageName.TRANSIENT,
  `Spooky headless output!`,
)

Polling hardware for data

We can request data by sending a query packet to hardware,

// Query the LED state
const queriedLedState = await query(`led_state`)
report.reportInfo(
    LogMessageName.TRANSIENT,
    `led state is ${queriedLedState}`,
)

Modifying hardware state

We simply use the write method provided by our session.

await write('lit_time', lit_time) sets the lit_time tracked variable to 1000ms.

Moving on

With the basics worked out, you can start making a great command-line UI for your own project!

Headless templates are a recent addition and additional CLI specific guides will be added soon. Key concepts such as custom data structures apply equally to both the CLI and front-end based templates.