Learn › Starting a project

Learn

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.

  1. What do you build? Pick a template: blank, rover-esp32, can-sensor-node or drone-fc (see the templates). You can also give owner/name, a template from the Arche Store.
  2. Which board? The template's board, no board, or a board from the board store. archec board list lists them.
  3. 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).
  4. The main parts, and what talks to what. Write one a -> b per line, for example lidar -> planner and planner -> 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.
  5. Generated code? none, c, embassy (Rust) or go. 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,motor answers "What will it do?" (what it does).
  • --name names the project. By default the name comes from the folder: my-drone gives project MyDrone "My drone".
  • --dry-run prints 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 add puts 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 uses and the include that archec shelf add writes.
  • 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; --template picks another one. Each kind sets the language of the behaviour; --handlers picks 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/ and generated/. src/ holds the code you fill in. It is generated, and you commit it. Write your code between the USER CODE BEGIN and USER CODE END markers: each archec gen keeps it (see regeneration). The rest of the generated code goes into generated/, with what the build writes. .gitignore leaves generated/ out.

  • A test for each part. A part that no test plan names gets a first test case in tests.arche. archec test runs 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.yml and .gitlab-ci.yml at the root. The first job checks the model (archec gen --target ci: archec check, archec ci). A code job then generates the code, builds it and runs its tests, with the tools it needs set up.

  • VS Code. .vscode/extensions.json recommends arche-lang and the extensions for the code. .vscode/tasks.json has 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 start archec live.

  • The first run. Once the files are written, archec runs archec check, archec test (the test plans in the simulator), archec gen for 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 new exits with 1. On a project archec just made, that is a bug in archec.
    • --no-run skips 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.

  • api answers HTTP: POST /orders, GET /orders/count, DELETE /orders.
  • orders checks each order.
  • store keeps 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 Host processor (compute { os linux }) in a Machine platform, and deployment OnHost. It has one binary, in language 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 each handler GET "/path" -> fn of the model;
    • http_test.go: a test of each route.

    Your code goes in two places, and archec gen keeps both. The first is the USER CODE regions: <Part>.init, and the body of each function the model gives no body. The second is user.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 into generated/bin/), go vet and go 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). ADDR sets 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.go beside 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:

  • ingest takes a reading every second;
  • processor summarises it;
  • dashboard shows the summary, and goes to Alarm when a reading is over LIMIT.
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 test runs 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 CODE region 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) and ARCHE_PEER_<PART> (for example http://processor:8080). net_test.go tests both ends of each link.

  • The images and the manifests, in generated/. These are regenerated, and not committed.

    • generated/containerd has a Containerfile per container, which takes the program from bin/<part>, and containers/server/compose.yaml.
    • generated/k8s/k8s has a Kubernetes Deployment per container, for kubectl 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:

  1. It builds each program for the server's Linux, into generated/containerd/bin.
  2. It runs go vet and go test on each program.
  3. It checks the compose file (docker-compose config) and the manifests (kubectl kustomize), without a daemon or a cluster.
  4. It builds the images with podman, if podman's machine is running. Otherwise it says podman machine start and 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 in port 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); and main, 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 High above 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=src is given with no type, so CMake makes it an absolute path from the folder you run it in.
  • ./build/app/app with no number runs until Ctrl-C.
  • The Qt steps need Qt 6: qmake6 on the PATH, and its CMake config. Without it they are skipped with a note.

Limits:

  • make test runs the C that --target c-tests writes from the model. It does not run your code in src/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:

  1. It checks the model.
  2. It runs the test plan in the simulator.
  3. It writes the C, builds it with CMake, and runs ctest.
  4. 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:

  1. Set owner, license and export-control in library.arche. The template writes owner your-name, Apache-2.0 and none. These are your statements as the publisher.
  2. Run archec store check ., then archec 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 gen itself 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, square pick robot-draw; cap, bottle, unscrew robot-cap; cube, puzzle robot-cube. For robot-draw, triangle or star and a size (9 cm) give the shape to draw.
  • With an AI allowed (archec config ai local-ai or online), 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 model claude-opus-5-5).
  • It sends them only when you run the command.
  • --dry-run prints 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 --describe is 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 add and archec device add, to add a board or a sensor later.
  • archec explain <code>: what a message of archec check means.