Starting a project: archec new
archec new makes a new project that already works. Its model passes
archec check, its test runs in the simulator, and it can generate firmware.
So you start by changing names, not by facing an empty file.
A first project#
archec new my-rover --template blank --yes
+ project MyRover "My rover"
+ handlers typescript
✓ my-rover: 3 file(s)
✓ archec check: no errors
Next:
archec check my-rover/main.arche
archec test my-rover/main.arche
code my-rover (the VS Code extension draws it)
It writes three files:
main.arche, the model;README.md, with the commands to run next;.gitignore.
Then check the model and run its test:
cd my-rover
archec check main.arche
archec test main.arche
✓ no errors
...
PASS TP-BLINK/TC-BLINK-01 It turns on, then off
1/1 passed, 0 failing, 0 known failure(s)
code . opens the folder in VS Code, and the extension draws the model.
The questions#
Without --yes, and in a terminal, archec new my-rover asks five questions.
With kinds there are six: the kind of project comes first.
- What do you build? Pick a template:
blank,rover-esp32,can-sensor-nodeordrone-fc(see the templates). You can also giveowner/name, a template from the Arche Store. - Which board? The template's board, no board, or a board from the
board store.
archec board listlists them. - What will it do? Optional: numbers or words, separated by commas, or nothing. Each answer adds the store's parts that do it and fit the board (see what it does).
- The main parts, and what talks to what. Write one
a -> bper line, for examplelidar -> plannerandplanner -> motors. A name alone is a part with no link yet. For a part that is not there, archec makes a component, a part, a port at each end and a message between them. A part the template already has gets a new port. - Generated code?
none,c,embassy(Rust) orgo. If you picked a board and the model has no deployment yet, archec writes one: one firmware on the board, with one thread that runs the parts.
archec checks each step as archec check does. A step that would add an error
is left out, and the output says so in a note. An example: a board whose ports
the template's links do not find.
Without questions#
The flags answer the questions. --yes takes the default answer for the
others. archec also takes the defaults when the input is not a terminal.
archec new my-node --template can-sensor-node --yes
archec new my-robot --board raspberry-pi-4 --parts "lidar -> planner, planner -> motors" --target go --yes
archec new my-drone --template drone-fc --board nucleo-f446re --name "Racer" --dry-run
--does temperature,motoranswers "What will it do?" (what it does).--namenames the project. By default the name comes from the folder:my-dronegivesproject MyDrone "My drone".--dry-runprints the files and writes nothing. The last line above prints:
+ project Racer "Racer"
+ handlers typescript
+ derived-from "arche/drone-fc@0.1.0"
+ board nucleo-f446re (in place of the template's nucleo-h743zi2)
── .gitignore ──
...
What it does#
The third question, or --does, takes plain choices. Each one adds parts
from the shelves: a device of the store that does it, and the
algorithms that go with it.
| Choice | Also understood | Adds |
|---|---|---|
temperature |
humidity, pressure, weather |
a BME280 (I²C), else an SHT3x, a DS18B20 (1-Wire on a GPIO pin), a thermistor (an analog pin) |
motion |
imu, tilt, acceleration |
an MPU6050 (I²C), else an ADXL345; the ComplementaryFilter algorithm |
distance |
range, ultrasonic, obstacle |
an HC-SR04 (GPIO pins), else a LIDAR-Lite (I²C) |
light |
lux, brightness |
a BH1750 (I²C), else a TSL2561, a Grove light sensor (an analog pin) |
compass |
heading, magnetometer |
an HMC5883L (I²C) |
presence |
pir |
a PIR motion sensor (a GPIO pin) |
button |
switch, press |
a button (a GPIO pin); the Debounce algorithm |
led |
lamp |
an LED (a GPIO pin) |
relay |
fan, pump |
a relay (a GPIO pin) |
motor |
dc-motor, wheel |
a DC motor (a GPIO pin); the Ramp algorithm |
servo |
a hobby servo (a PWM pin) | |
display |
screen, lcd, oled |
an SSD1306 OLED (I²C), else an HD44780 (GPIO pins) |
setpoint |
pid, control |
the Pid algorithm |
thermostat |
heating, cooling |
a temperature sensor, a relay and the Thermostat algorithm |
filter |
smooth, low-pass, noise |
the LowPass algorithm |
archec new greenhouse --board nucleo-g474re --does thermostat,display --yes
+ board nucleo-g474re: uses arche-hw-store "^0.1", include …, system GreenhouseHw { part nucleo_g474re: NucleoG474RE }
+ thermostat: part air: Bme280 — BME280 (on nucleo_g474re.i2c1)
+ thermostat: part relay: GpioRelay — Relay (on a GPIO pin)
+ thermostat: part thermostat: Thermostat — arche-algorithms (in Main)
+ display: part display: Ssd1306 — SSD1306 (on nucleo_g474re.i2c1)
- A device must fit the board: an I²C device only if the board has I²C, an analog one only if it has an analog pin or an ADC. archec takes the first device of the list that fits, then any other device of the store that does the same thing. If none fits, a note says so and names the shelf to look at.
- With a board, a device goes in the hardware system, beside the board, as
archec device addputs it. An I²C or SPI device is linked to the board's bus (nucleo_g474re.i2c1 -> air.i2c). Pins are yours to link. Without a board, the devices go in the logical system. - An algorithm is a part of the logical system, with the
usesand theincludethatarchec shelf addwrites. - The parts are not linked to your logic yet. A component says what it needs
(
out air: requires TemperatureSensor) and the system links it (ctl.air -> air.temperature_sensor), as in boards.md.
Each part is a step, checked like the others: one that would add an error is left out, with a note. In VS Code, New Project asks the same question, as a list where you tick the choices.
The templates#
| Template | What it is | Board |
|---|---|---|
blank |
One component that blinks, a requirement and its test. The smallest project that does something. | none (--board adds one) |
rover-esp32 |
A wheeled rover: a remote, a distance sensor, two motors, and a drive controller. Its state machine stops before an obstacle. | ESP32-DevKitC |
can-sensor-node |
A temperature sent on CAN every 100 ms. A bad reading puts it in a fault state. A gateway on the bus resets it. | NUCLEO-G474RE (STM32G4, FDCAN) |
drone-fc |
A quadcopter flight controller: RC receiver, IMU, arming and failsafe, a 1 kHz rate loop, four ESCs. | NUCLEO-H743ZI2 |
ros2-rover |
A rover as ROS 2 nodes: lidar driver, planner, motor driver. A simulated world closes the loop, and the rover stops before the wall. | none (a Linux computer) |
robot-draw, robot-cap, robot-cube |
A small arm in MuJoCo draws a square, unscrews a bottle cap, turns a cube face; requirements, test cases against the arm, tunable constants (robot prototyping). | none (--kind robot puts the planner on a Pico) |
The templates are in lib/templates/, beside archec. Each one is a library
with kind template. archec store seed publishes them, so a store has them
as arche/<id>. To make your own template, make a library folder with
kind template and a main.arche, and publish it like any package.
Kinds#
--kind says what the project is: firmware, a service, a robot… With a kind,
archec new does more than write a model that checks. It ends with a
repository that already builds and runs.
archec new my-node --kind firmware
First run (firmware):
✓ archec check
✓ archec test — 3/3 pass
✓ archec gen --target c
✓ archec gen --target c-tests
✓ make (rover_fw)
✓ the test plans on the C (make test) — 1/1 pass
✓ rover_fw runs 0.5 s on this computer
✓ first run: simulated 500 ms, built (make), 4/4 tests pass, rover_fw runs 0.5 s on this computer
In a terminal, without --kind, the first question is What kind of
project? You answer with one of the kinds below, or with a template or a
store package as before. With --describe, archec picks the kind from the
words of your sentence (firmware, esp32, stm32…). --kind overrides it.
Every kind gets the following:
A template, a code language and a deployment. Each kind starts from its own template;
--templatepicks another one. Each kind sets the language of the behaviour;--handlerspicks another one. If the project has no deployment, archec writes the one its code needs. As with every step, a step that would add an error is left out, with a note.src/andgenerated/.src/holds the code you fill in. It is generated, and you commit it. Write your code between theUSER CODE BEGINandUSER CODE ENDmarkers: eacharchec genkeeps it (see regeneration). The rest of the generated code goes intogenerated/, with what the build writes..gitignoreleavesgenerated/out.A test for each part. A part that no test plan names gets a first test case in
tests.arche.archec testruns it in the simulator. The case checks one of these:- a message that a link brings to the part moves its state machine, or reaches it;
- what the part sends reaches the part at the other end;
- the part starts in its first state.
Change these cases to say what the part must do.
CI.
.github/workflows/archec.ymland.gitlab-ci.ymlat the root. The first job checks the model (archec gen --target ci:archec check,archec ci). Acodejob then generates the code, builds it and runs its tests, with the tools it needs set up.VS Code.
.vscode/extensions.jsonrecommends arche-lang and the extensions for the code..vscode/tasks.jsonhas three tasks: build (generate, then build), test (the simulator, then the code's tests) and archec: live. When the folder opens, the extension offers to startarchec live.The first run. Once the files are written, archec runs
archec check,archec test(the test plans in the simulator),archec genfor each target, then the kind's build and its tests. It prints one line per step, then a summary line.- A tool this computer does not have skips its step, with a note. So does a daemon that is not running (podman, Docker).
- A step that fails shows the end of its output, and
archec newexits with 1. On a project archec just made, that is a bug in archec. --no-runskips the first run.archec new --first-run [dir]runs it again later. The kind is saved in.archec/kind.json.
| Kind | What you get | Code | Built and tested with |
|---|---|---|---|
firmware |
Code for a microcontroller board: the model's parts placed on the board, its firmware generated. Template rover-esp32; --board another, --target c (default), embassy or go. |
src/c/ (or src/embassy/, src/go/), one folder per binary; generated/c-tests/ |
C: make (the POSIX runtime, on this computer), the binary run for half a second, the test plans as C unit tests (make test). Go: go build, go vet. Rust: cargo check when the board's target is installed (rustup target list --installed); an ESP32's Xtensa target needs Espressif's toolchain, so it is skipped. |
service |
A backend service in Go on a Linux or macOS host, no board. Template web-service: api -> orders -> store, HTTP routes, a store machine. |
src/go/<project>/ (with http.go, the routes); generated/openapi/ |
go build, go vet, go test (each route answers); the program serves HTTP. |
containers |
Several programs, each in its own container, talking over the network. Template container-pipeline: ingest -> processor -> dashboard. |
src/go/<program>/ per container; generated/containerd/, generated/k8s/ |
go build for the container's Linux, go vet, go test; the compose file and the Kubernetes manifests read offline; podman build of each image when podman (or Docker) is running. |
ros2 |
A robot as ROS 2 nodes, with a simulated world closing the loop. Template ros2-rover: lidar, planner, motors. |
src/ros2*/ (packages, nodes, launch); generated/c-tests/, generated/gazebo/ |
make test (the C tests), a static check of the packages; with ROS 2: colcon build, then the nodes launched against the world. CI runs it in ros:jazzy-ros-base. |
desktop |
A program on a PC: parts on threads, an operator screen. Template desktop-app: a source, a limit monitor, a console. |
src/c/, src/ui-qml/<Ui>/; generated/cmake/, generated/c-tests/, generated/ui-web/ |
CMake, the C tests, the program run for a second; the Qt screen built and started off screen when Qt 6 is there. |
library |
Components others include: a store package and a C library. Template component-library: a threshold, a latch, an example system. |
src/c/; CMakeLists.txt (yours); generated/c-tests/ |
CMake, ctest (a test per case), and archec store publish . --dry-run: the package as published compiles. |
robot |
A small arm and a task in MuJoCo: draw a shape, unscrew a cap, turn a cube face. Template robot-draw, or the scene --describe names. |
src/c/arm_fw/ (the planner, for a Raspberry Pi Pico); generated/mujoco/ |
make (the POSIX runtime), the binary run for half a second; with MuJoCo's Python, the test plan against the arm (archec sim --plant … --test), skipped with a note without it. archec test allows the cases that need the arm (tests/mujoco.allow). |
A web service (--kind service)#
archec new my-shop --kind service
archec new my-shop --kind service --parts "api -> orders, orders -> store, store -> billing"
This kind makes a backend service in Go: one process on a Linux or macOS
host, with no board. It starts from the template web-service, with three
modules as parts: api -> orders -> store.
apianswers HTTP:POST /orders,GET /orders/count,DELETE /orders.orderschecks each order.storekeeps the orders that were accepted.
The model has four requirements, and a test plan that passes in the simulator.
The behaviour is written in the action language (handlers arche). Arche's
simulator runs it, and archec translates it to Go.
What archec new adds and makes:
The deployment. A
Hostprocessor (compute { os linux }) in aMachineplatform, anddeployment OnHost. It has one binary, inlanguage go, with one thread that runs the parts. So the parts handle their messages and HTTP calls one at a time.src/go/<project>/, the Go program (archec gen --target go -o src, committed). All of these files are regenerated:parts.go: each part, with its variables, functions and state machine;main.go: the parts wired as the model links them, with a goroutine per thread;http.go: a route for eachhandler GET "/path" -> fnof the model;http_test.go: a test of each route.
Your code goes in two places, and
archec genkeeps both. The first is the USER CODE regions:<Part>.init, and the body of each function the model gives no body. The second isuser.go, which is written once.generated/openapi/<Component>.json(--target openapi): the same API as OpenAPI 3.1, for clients and docs.The first run:
go build(the binary goes intogenerated/bin/),go vetandgo test. Without Go on the PATH, these steps are skipped with a note.
Run it:
cd src/go/my_shop
go run . # listens on :8080; ADDR=:9000 for another
curl -X POST -d '{"item":7,"qty":3}' localhost:8080/orders
curl localhost:8080/orders/count
How a route works:
- It takes its function's parameters from the path (
/items/{id}). Otherwise it takes them from the query (GET, DELETE, HEAD) or from a JSON body (POST, PUT, PATCH). - It answers with the function's return value as JSON: a struct, with the model's field names. When the function returns nothing, it answers 204.
- A parameter that does not parse gives a 400.
- The call runs on its part's thread, like a message. So a part never runs two things at once.
- The port comes from the part's
attr url(in the template:http://localhost:8080).ADDRsets another one.
To add a route, add a handler to a port of a part, and add its function:
in http: ethernet "HTTP" {
handler GET "/orders/{item}" -> stock_of
}
fn stock_of "Stock of an item" (item: uint32) -> uint32 {
```arche
return stock
```
}
Then run archec gen main.arche --target go -o src and
archec gen main.arche --target openapi -o generated.
Limits:
- The simulator does not run HTTP. The test plan sends the messages the
routes lead to instead:
send(api.orders, PLACE(…)). - The route test checks that each route answers with its status. It does not
check what the route answers: write your own
*_test.gobeside it for that. - A function the model declares without a body is a USER CODE region in Go. But Arche's simulator stops when it calls that function. Give the function a body in the model when a test calls it.
Processes in containers (--kind containers)#
This kind makes several processes, each in its own container, talking over the
network. The template, container-pipeline, is a pipeline of three parts:
ingesttakes a reading every second;processorsummarises it;dashboardshows the summary, and goes toAlarmwhen a reading is overLIMIT.
archec new my-pipes --kind containers
What you get:
A model that simulates. Three components, their messages, three requirements and a test plan. The deployment puts each part in a container, as a Go program, on a Linux server (
runtime containerd).archec testruns the template's test cases, plus one for the deployment: a reading every second.The code, in
src/go/<part>, for you to fill in (--target go). Each part is a Go program, with:- its variables, its ```arche bodies translated to Go, and its state machine;
- a
USER CODEregion in each constructor, and in each function that has no body in the model; user.go, written once.
A link between two parts is JSON over HTTP (
net.go). Each program listens on its own port, starting from 9001 in the order of the deployment. It reaches the others on 127.0.0.1. Two environment variables change this:ARCHE_LISTEN(for example:8080) andARCHE_PEER_<PART>(for examplehttp://processor:8080).net_test.gotests both ends of each link.The images and the manifests, in
generated/. These are regenerated, and not committed.generated/containerdhas a Containerfile per container, which takes the program frombin/<part>, andcontainers/server/compose.yaml.generated/k8s/k8shas a Kubernetes Deployment per container, forkubectl apply -k.
The containers use the host's network. So the same ports work on one machine, under compose, and on a node of a cluster.
The first run does the following:
- It builds each program for the server's Linux, into
generated/containerd/bin. - It runs
go vetandgo teston each program. - It checks the compose file (
docker-compose config) and the manifests (kubectl kustomize), without a daemon or a cluster. - It builds the images with podman, if podman's machine is running.
Otherwise it says
podman machine startand goes on.
Run it on your machine, with one terminal per part
(cd src/go/ingest && go run .), or in containers:
podman compose -f generated/containerd/containers/server/compose.yaml up
The server's isa (instruction set) is the one of the machine that made the
project, for example arm64 on an ARM Mac. So the images run there. For an
x86 server, write isa x86_64. The programs and the images are then built for
linux/amd64. These do not run under podman on an ARM Mac, because Go's
runtime crashes under emulation. Build them in CI or on the server.
More about parts:
- A part you add (
--parts "processor -> archive") gets its own container and program. - A part with no
inport runs its first function, with no parameters, every second. The other parts run when they receive a message. - A part with no behaviour yet is in no program. A link to it is left out until it does something.
ROS 2 robot (--kind ros2)#
archec new my-robot --kind ros2
This kind makes a robot as ROS 2 nodes. It starts from the template
ros2-rover, with three parts:
- a lidar driver;
- a planner that drives toward a wall, slows down as it gets closer, and stops 0.3 m before it;
- a motor driver that turns the speed into wheel speeds.
The world is a plant (kind plant): a part that stands for the physical
world. It moves the rover by its wheel speeds, and gives the lidar the distance
left. The simulator runs the plant with the rest, so the test plan runs with
nothing installed. The plant is not a node. On the robot, in Gazebo or in a
test script, something else plays the world.
What you get:
| Deployment | <Project>Ros2, with packaging ros2: one binary, <project>_nodes, on a Linux computer. It has a process for each part that has behaviour and is not hardware (the plant is left out). |
src/ (yours, committed) |
Made by archec gen --target ros2: the message package <project>_msgs (src/ros2); the package of nodes src/ros2_nodes/<project>_nodes, with an rclcpp executable per process around the part's C module; and <project>_ros2_bringup, with the launch file. |
generated/ (ignored) |
c-tests (the test plans as C unit tests of the same C modules), gazebo (the world for gz sim: SDF, bridge, adapter), colcon (colcon's build, install and log). |
| Tests | The test plan in the simulator (archec test). make test in generated/c-tests. tests/ros2_check.py --static: each package.xml parses, the Python compiles, each launch file has generate_launch_description, the C modules compile. tests/ros2_check.py with ROS 2: it launches the nodes and plays the world, and the rover must stop between 0.25 and 0.35 m. |
| Build | colcon build --base-paths src, into generated/colcon. |
| CI | The build and test steps, in the ros:jazzy-ros-base image (ciContainer). |
Your code in the nodes goes in their USER CODE regions, and archec gen keeps
it. The regions are:
- in each
src/<exe>.cpp: the includes; the end of each node's constructor (<part>.node, for example a subscription to a real driver's topic); the node's members (<part>.members); andmain, before the threads start; - in
CMakeLists.txt: one region for more packages and sources; - in each C module: the includes, and the end of its init.
The behaviour itself is in the model.
Without ROS 2 on the machine (on macOS, for example), colcon build and the
live run are skipped with a note. The simulator, the C unit tests and the
package checks still run. To build anyway, use the ROS 2 container:
podman run --rm -v "$PWD:/ws" -w /ws ros:jazzy-ros-base bash -c \
'. /opt/ros/jazzy/setup.sh && colcon --log-base generated/colcon/log build --base-paths src --build-base generated/colcon/build --install-base generated/colcon/install && . generated/colcon/install/setup.sh && python3 tests/ros2_check.py'
Desktop program (--kind desktop)#
This kind makes a program on a PC, running Linux, macOS or Windows. Examples:
a controller tool, a test bench, a simulator's front end. The parts are C
modules on a few threads of one program. The part with a ui { } is the
program's screen.
archec new my-bench --kind desktop
It starts from the desktop-app template, which has:
- a signal source that sends a sample every 10 ms;
- a monitor that goes
Highabove a limit, and logs each alarm; - an operator console, with a gauge and Start/Stop buttons;
- three requirements, and the test plan that verifies them.
Its deployment puts one program, app, on the PC. The source runs on a 10 ms
thread. The monitor and the console run on another thread. A project that
comes without a deployment gets one program, with a thread per part.
What you get:
| Where | What | Committed |
|---|---|---|
src/c/ |
The C of the parts (--target c). Your code goes between the USER CODE BEGIN and END markers (Monitor.init, Monitor.includes, app.start in app/wiring.c, …), and archec gen keeps it. |
yes |
src/ui-qml/Console/ |
The screen as a Qt Quick application (--target ui-qml). main.cpp and CMakeLists.txt are yours; the QML comes from the model. |
yes |
generated/cmake/ |
The CMake project of the program (--target cmake). |
no |
generated/c-tests/ |
The test plan as C unit tests (--target c-tests). |
no |
generated/ui-web/ |
The screen as a web page, with the model simulated in it. Open index.html. |
no |
The first run builds and runs it, with these commands:
archec test main.arche # the test plan, simulated
cmake -S generated/cmake -B build -DARCHE_GEN=src # the C is in src/c
cmake --build build
make -C generated/c-tests test # 3 passed, 0 failed
./build/app/app 1000 # runs for a second, then exits
cmake -S src/ui-qml/Console -B build/ui-Console && cmake --build build/ui-Console
QT_QPA_PLATFORM=offscreen ARCHE_UI_QUIT_AFTER=1000 ./build/ui-Console/console_ui
Notes on these commands:
-DARCHE_GEN=srcis given with no type, so CMake makes it an absolute path from the folder you run it in../build/app/appwith no number runs until Ctrl-C.- The Qt steps need Qt 6:
qmake6on the PATH, and its CMake config. Without it they are skipped with a note.
Limits:
make testruns the C that--target c-testswrites from the model. It does not run your code insrc/c/. The program builds and runs what you write in a region, but no unit test covers it.- The screen and the program are not connected yet. The Qt screen reads its
values over a WebSocket (
ARCHE_UI_WS, see ui), and the C program does not serve one. The web page simulates the model by itself. - On Windows, with a multi-configuration generator (Visual Studio), the
program is at
build/app/Debug/app.exe. The first run does not look there.
Component library (--kind library)#
archec new my-sensors --kind library
This kind makes a library of components that other projects include. It has
two forms: an Arche Store package (the model) and a C library built with CMake
(the code). It starts from the component-library template:
| File | What it is |
|---|---|
components.arche |
The library: its messages, requirements and components (a threshold with hysteresis, a latch). |
main.arche |
The project, and a small system that uses the components (Example), with the test plan. |
library.arche |
The store's card: kind library, its name (my-sensors), version, owner, license, export control. |
CMakeLists.txt |
The CMake library my_sensors, its ports my_sensors_ports, and a ctest test per case. It is yours, written once. |
src/c/ |
The C of each component (archec gen --target c -o src). Your code between the USER CODE markers is kept. |
generated/c-tests/ |
The test plan as C (--target c-tests), which ctest runs on src/c. |
The first run does the following:
- It checks the model.
- It runs the test plan in the simulator.
- It writes the C, builds it with CMake, and runs ctest.
- It packs the folder as the store would, and compiles it as the store's
validator does (
archec store publish . --dry-run). Nothing is sent.
A library has no deployment, because it does not run anywhere by itself.
--target c writes the components without one. What each component sends goes
through a function in src/c/<component>_ports.c. The project that uses the
library writes these functions. The file is a start: it encodes the message,
and leaves the sending to you. The C tests carry the messages between the
example's parts themselves.
To use the C in another CMake project:
add_subdirectory(path/to/my-sensors)
target_link_libraries(app PRIVATE my_sensors) # and my_sensors_ports, or your own send functions
To publish the library:
- Set
owner,licenseandexport-controlinlibrary.arche. The template writesowner your-name,Apache-2.0andnone. These are your statements as the publisher. - Run
archec store check ., thenarchec store publish ..
A project takes the library with archec add main.arche your-name/my-sensors,
and includes my-sensors/components.arche. What archec builds (generated/,
arche-out/) is not part of the package.
Limits:
- The C goes with the package as you wrote it. But a project that includes the
components and runs
archec genitself writes their C again, without the code in your regions. Use the library's CMake target for the code.
Robot arm (--kind robot)#
archec new my-arm --kind robot --describe "unscrew a bottle cap"
This kind starts from one of the robot scenes: robot-draw, robot-cap or
robot-cube (robot prototyping). With --describe,
the sentence picks the scene:
- Offline (the default), its words do:
draw,pen,squarepick robot-draw;cap,bottle,unscrewrobot-cap;cube,puzzlerobot-cube. For robot-draw,triangleorstarand a size (9 cm) give the shape to draw. - With an AI allowed (
archec config ai local-aioronline), the model reads the sentence and answers the same: a scene, a shape, a size. An answer that is not one of them falls back to the words. The model writes nothing else.
# scene: robot-draw, a triangle 90 mm across (the words "draw", "triangle")
The deployment puts the planner on a Raspberry Pi Pico. The arm, the object and the checker (the tracer, the bench) are the simulation's: they are not placed. The C builds for this computer; the servo and finger drivers are yours to write in its USER CODE regions.
Remixing a store package#
Any package of the store can be the start of a project: a whole architecture, a template, a board.
archec new my-car --from arche/autonomous-car
archec new my-node --from acme/can-node@^1.2 --store https://store.example.com
The project is a copy, not a dependency. The files are yours to change, and
nothing updates them behind your back. (archec add is for a library you
use.) archec checks the package as archec add does: its hash, its
publisher's signature, and the files' fingerprint. What the package uses from
the store comes along too.
The project records where it came from:
project MyCar "My car" {
version "0.1.0"
derived-from "arche/autonomous-car@0.3.0"
}
When you publish the project, its library keeps that line. The store's package page shows the family: what the package was derived from, and what was derived from it.
In VS Code, a package in the Store view has Use as Starting Point. It asks
for a folder, and opens the new main.arche. Arche: New Project… in the
command palette asks the five questions above.
From a description#
archec new my-robot --describe "a robot with 2 motors, a lidar and a Raspberry Pi"
Claude writes the first model. It gets a short reference of the language, the
boards of the board store, and a template as an example. archec checks what
comes back, and sends the errors to Claude, which corrects them. This repeats
up to four rounds (--rounds changes it). The result is a first draft: read it
before you trust it.
When the description has a display (a screen, a dashboard, an HMI, a touch
panel, an OLED), Claude also gets the ui { } reference, and is asked
for the screens. The component that owns the display gets a ui bound to what
the model sends it. archec checks it like the rest.
What is sent, and when:
- archec sends your description, and
archec check's messages about what Claude wrote, to the Anthropic API (the modelclaude-opus-5-5). - It sends them only when you run the command.
--dry-runprints the whole prompt and sends nothing.- It needs
ANTHROPIC_API_KEY.
Limits#
- The test cases a kind writes for each part are first cases, not a specification. Change them to say what the part must do.
- A step that would add an error (a board, a link, a deployment) is left out with a note, not forced in.
- A model written
--describeis a first draft from a language model. Read it before you trust it. - Each kind has limits of its own, listed in its section above.
Next#
- The tutorial: what each line of a model means, from a water pump to its firmware.
- Boards:
archec board addandarchec device add, to add a board or a sensor later. archec explain <code>: what a message ofarchec checkmeans.