More › shelves

More

Shelves: take it, don't rewrite it

Most projects need the same things: a vector, a GPS fix, a battery's voltage, a board, a temperature sensor, a PID controller. The store keeps them on six shelves, so you take them instead of writing them again.

Shelf What is on it Where it comes from
types Records and quantities: Vec3, Pose2D, ImuSample, GpsFix, BatteryState, Voltage, Temperature… arche-types, shipped with archec
units The units archec knows, by quantity: mAh, lx, µT, N·m, %RH, dBm… built into archec
boards Development boards: their processors, connectors and pins arche-hw-store, shipped with archec
drivers One interface per peripheral (GPIO, UART, I²C, SPI, CAN…) and its code libraries that say shelf drivers
sensors Sensors and actuators, grouped by what they do, with their accuracy, their simulated version and their drivers arche-hw-store: sensors.arche and the devices, and libraries that say shelf sensors
algorithms Controllers, filters and checks, written once in the action language libraries that say shelf algorithms

Everything shipped with archec works offline: no store, no network.

Look at a shelf#

archec shelf                 # the six shelves and how many pieces each has
archec shelf units           # the units, grouped by quantity
archec shelf types ImuSample # one piece: its card

Every piece has the same card#

A unit, a board and a filter all have the same seven lines, in the same order. Once you have read one card, you can read them all.

IMU sample  (ImuSample)  — Types, arche/arche-types

  Does        One reading of an inertial measurement unit: acceleration and turn rate on three axes
  Gives       stamp Timestamp · ax m/s² -160..160 · ay m/s² -160..160 · …
  Plugs into  a message or a field: `message IMU_SAMPLE: ImuSample`
  Add it      archec shelf add main.arche ImuSample
  Runs on     simulator · C · C++ · Rust · Go · Python · TypeScript
  Tested      built by archec's tests · no hardware needed
  From        arche/arche-types, Apache-2.0
  • Does: what it does, in plain words.
  • Gives: what comes out, with units and ranges. For a unit, this line is Measures: the quantity.
  • Plugs into: the bus, the address, the supply. For an algorithm, this line is Inputs and outputs.
  • Add it: the one command that adds it to your project.
  • Runs on: the simulator, Go on Linux, Rust on Embassy…
  • Tested: what has run it. The cards are honest: no board or sensor of the store has run on real hardware yet, and each card says so.
  • From: where it comes from, and its license.

The card is read from the files themselves: the /// comment above a declaration, its label, its fields and their units, a part's ports and address, its product { … }, and the library's library.arche. Change the file, and the card changes.

--json gives the same, for tools: archec shelf sensors bme280 --json.

Its arche code#

Under the card comes the piece's arche code, as its library writes it, with its /// comment. A long one, such as a board with all its pins, says how many lines it has instead. --code prints the code alone, to read or to copy:

archec shelf algorithms Pid --code
archec shelf boards nucleo-g474re --code > my-board.arche

A unit that archec knows without a declaration has no code: a project writes it as it is (4000mAh). On the store's Shelves page, Its arche code opens under each card, and in VS Code the card's panel shows it, with Copy the Code.

Add a piece#

archec shelf add main.arche Voltage

This writes two lines, and only if the project still builds:

project Rover {
  uses arche-types "^0.1"
}
include "arche-types/quantities.arche"

Then use it: var vbat: Voltage, message IMU: ImuSample. A board or a device is added as archec board add and archec device add do. A unit needs nothing: write it after a number (4000mAh) or on a field (capacity: float32 unit mAh).

Units#

archec knows which quantity each unit measures, and warns when two different quantities are added or compared: 2N·m + 3J adds an energy to a torque. Nothing is ever converted for you. archec shelf units lists every unit with its name and an everyday example, such as "a phone battery: 4000 mAh".

Some units have several spellings: µT or uT, N·m, N*m or Nm, rad/s² or rad/s2, µg/m³ or ug/m3, lx or lux, G or gauss.

Put your own library on a shelf#

A library joins a shelf with one line in its library.arche:

library acme-control "Controllers" {
  version "1.0.0"
  owner acme
  license "MIT"
  shelf algorithms
}

What goes on the shelf is read from its .arche files (but boards/, devices/, tests/ and examples/):

  • shelf types: each type, struct, enum, union and message;
  • shelf units: each unit;
  • shelf drivers: each component and interface;
  • shelf sensors and shelf algorithms: each component.

A library can be on several shelves: shelf algorithms, types. A collection with a boards/ folder is on the boards shelf, and one with a devices/ folder on the sensors shelf, without saying it. A test plan of the library (in tests/ too) whose text names a piece counts as that piece's tests on its card.

Write a /// comment above each piece: its first sentence is the card's Does line.

Sensors by what they do#

The sensors shelf is grouped by what a part does, not by its part number: Temperature, Humidity, Air pressure, Acceleration, Distance, Light, Button, LED, Relay, Servo, Display… Each group starts with its interface, from lib/arche-hw-store/sensors.arche, then the devices that provide it. A device that does several things is under each of them. The devices that do none of them (ADCs, port expanders) come last, by bus.

$ archec shelf sensors
Temperature
  TemperatureSensor           Measures a temperature
  bme280                      TemperatureSensor, HumiditySensor, PressureSensor: …
  ds18b20                     TemperatureSensor: …
Humidity
  HumiditySensor              Measures the air's relative humidity
  …

A device's card says what it does, its readings with their unit and accuracy, and its supply:

BME280  (bme280)  — Sensors and actuators, arche/arche-hw-store

  Does        TemperatureSensor, HumiditySensor, PressureSensor: BME280Driver is a driver for …
  Gives       temperature °C ±1, step 0.01 · humidity %RH ±3, step 0.008 · pressure Pa ±100, step 0.18
  Plugs into  I²C at 0x77 · 1.71–3.6 V · 3.6 µA
  Add it      archec device add main.arche bme280
  Runs on     simulator · Go · Linux
  Tested      2 tests in the simulator · not yet on hardware
  From        Go driver i2c.NewBME280Driver, from Gobot v2.6.0, arche/arche-hw-store, Apache-2.0
  • Gives: an operation of each interface it provides, with the port's noise (±) and resolution (step).
  • Runs on: "simulator" when its interfaces have a simulated version.
  • Tested: the cases of the collection's test plans (tests/) that name the device's component (Bme280) or the interface.

An interface's card says its operations and what the simulator does for it. archec shelf add main.arche TemperatureSensor writes the uses and the include of sensors.arche. In the editor, after part air: , completion lists the devices by group ("Temperature: BME280 (I²C, ±1 °C)"). Choosing one writes its include and the project's uses.

How a model uses them, swaps one for another and runs them in the simulator is in boards.md.

In VS Code#

The Store Shelves view of the Arche side bar has the six shelves, with how many pieces each has. (It was the Boards view: its place, its commands and its settings did not change.)

STORE SHELVES
▸ In this project             the boards the model uses
▸ Types                  39
▾ Boards                 24
  ▸ arche-hw-store 0.1.0      built in, by vendor
▾ Sensors and actuators 110
  ▾ Temperature
      TemperatureSensor       Measures a temperature
      BME280                  I²C, ±1 °C
▸ Algorithms             20
  • Each piece shows its one-line summary, and its card as a tooltip.
  • A click opens the card in a panel: the seven lines, what it writes, and for an algorithm its response chart (response.svg). The panel's Add to This Project does what archec shelf add does on the model's main file. A board goes to Add Board to Model… and a device to Add Device to Model…, which ask the part's name and where it goes. A unit has nothing to add. Copy the Lines copies what it writes. The panel also shows the piece's arche code (folded when it is long), and Copy the Code copies it.
  • Add to This Project is also in a piece's menu, and in the command palette, where it asks which piece.
  • Filter Shelves… keeps the pieces whose name, summary or group has the word, on every shelf: temperature, esp32, i2c.

archec new asks what the project will do and takes the matching pieces (new.md). The playground has an Add from the store menu with the same shelves and cards.

Limits#

  • Nothing on the hardware shelves has run on a real board yet. The cards say "not yet on hardware" until someone tries it.
  • The drivers shelf is empty until a library that says shelf drivers is installed. The algorithms shelf holds what archec ships, arche-algorithms (algorithms); its tests (tests/) are not pieces.
  • A card shows accuracy only when the model gives it (a port's noise). The store's devices give it where the datasheet is clear; 32 of them do none of the interfaces and stay by their bus.
  • The store's Shelves page shows what archec ships. Packages published to a store are not on it yet, even when they say shelf.
  • archec does not tell a torque from an energy by its dimensions. A force times a length is taken where either goes.