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: eachtype,struct,enum,unionandmessage;shelf units: eachunit;shelf drivers: eachcomponentandinterface;shelf sensorsandshelf algorithms: eachcomponent.
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(±) andresolution(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 whatarchec shelf adddoes 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 driversis 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.