Learn › Overview

Learn

arche-lang documentation

The pages are grouped by what you want to do. New to arche-lang? Follow Learn in order. Then come back for a guide when you have a task, or for the reference when you need an exact answer.

Learn#

Read these five in order.

  1. Concepts — Understand the five ideas every model is built from, before any syntax.
  2. Tutorial — Build a small water pump controller, from the first model to working firmware.
  3. Tutorial on a board — Take a greenhouse thermostat to a real NUCLEO-F446RE, with a sensor and a fan, and measure it.
  4. Cheat sheet — Find the core of the language and the everyday commands on one page.
  5. Starting a project — Start your own project from a template, a shared package or a sentence, with a model that already works.

How-to guides#

Each guide shows how to do one task.

Write and check a model#

Hardware, robots and physics#

  • Deployment — Say which processor and thread each part runs on, then follow the running system live.
  • Boards — Build on a known board such as an ESP32 or a Raspberry Pi, or describe your own.
  • Device drivers on microcontrollers — Drive a sensor or an actuator from an STM32, nRF, RP2040 or ESP32 board, in Rust with Embassy.
  • Robots — Run your robot's software on ROS 2 and test it in a simulated world.
  • Robot prototyping — Say a task in words, watch a small arm do it in MuJoCo, tune it until its requirements pass.
  • Physics — Fit a physical model to your measurements and run simulated equipment beside the model.
  • CAD as code — Write a part's shape as Python, measure it, and prove its size, mass and clearances against the requirements.
  • FPGA components — Write hardware as a component with a clock, generate its VHDL, and run its test cases in GHDL.
  • A 5G cell search, end to end — Follow a signal-processing chain from its requirements to an FPGA correlator: OFDM, noise, an FFT, tests at set SNRs, GHDL and synthesis.
  • Tuning to the requirements — Let archec try a controller's gains until its test cases and requirements pass.

Verify and assess#

Generate code#

  • Regenerating code — Keep the code you wrote by hand each time archec writes the generated code again.
  • The quality of the generated code — Check that the generated code builds cleanly, and trace each problem back to the model.
  • C++ — Generate C++ for a computer that runs Linux or a full operating system.
  • Register maps — Generate matching register maps for the software, the hardware and the documents.
  • Integration targets — Generate the files that the tools around your firmware read, such as protocol descriptions and build scripts.
  • Generators of your own — Add a code generator for your company's own format.
  • Plugins — Package generators, importers and exporters together in one folder.

Documents and presentations#

  • Template documents — Fill your own Word or LibreOffice document with content from the model.
  • Animations — Add moving pictures to your presentations that stay true to the model.

Share, import and read code#

  • The Arche Store — Share your work with others, and use their packages safely in your project.
  • Shelves — Ready-made types, units, boards, drivers, sensors and algorithms to take instead of writing them again.
  • Algorithms — A PID, filters, a debounce, odometry, CRCs and more, tested in the simulator and generated for every target.
  • Importing — Bring in models from other tools, such as SysML v2, a CAN database or a robot description.
  • Understanding code — See who wrote a piece of code, what it does, and how existing code is organised.
  • AI-assisted engineering, offline — Keep code an AI wrote understood, with local checks; choose what may leave the machine.

Reference#

Exact answers, to look up when you need them.

  • The core — Read the whole core of the language in an evening: what edition 1.0 promises to keep, with one example of each construct.
  • The specification — Look up exactly what the language allows and what each construct means, the extensions too.
  • Editions — See what each edition changes, the stability promise, and how a renamed name keeps working for one edition.
  • Language reference — Look up any declaration, with its properties and an example. One page per group: structure, behaviour, requirements, deployment and more.
  • Commands — Look up any archec command and its options, one page per kind of task.
  • Error codes — Look up what an error or warning means and how to fix it. The editor and archec explain <code> link to the same page.
  • Code generation — See every kind of code archec can generate, and what each one writes.
  • Handlers — Look up exactly how behaviour code talks to the simulator, in each language.
  • Effective Arche — Look up each style warning and learn how to write a model that reads like every other one.
  • Glossary — Find a short definition of each word the docs use.

Explanation#

Background, to read when you want to know why.

  • How it maps to Arche — See what each part of your model becomes in the Arche project.
  • Qualifying archec — Understand how to show that archec can be trusted in a safety project.
  • Design notes — Learn why the language is designed the way it is, and how fast archec runs.
  • How arche-lang works — Explore the toolchain, described as a model in its own language.

Also: the project README, to install arche-lang, and the list of changes in each version.