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.
- Concepts — Understand the five ideas every model is built from, before any syntax.
- Tutorial — Build a small water pump controller, from the first model to working firmware.
- Tutorial on a board — Take a greenhouse thermostat to a real NUCLEO-F446RE, with a sensor and a fan, and measure it.
- Cheat sheet — Find the core of the language and the everyday commands on one page.
- 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#
- Fixes and the beginner level — Let archec fix the most common mistakes for you, and see simpler error messages.
- The VS Code extension — Write models in VS Code with diagnostics, completion, a live diagram and a debugger for the simulation.
- The Arche app — Open your project in Arche's visual editor and change it there.
- The browser simulator — Watch your model run in a web page, with nothing else to install.
- The product's user interface — Describe your product's screens in the model and let archec check them.
- Handlers in TypeScript or Python — Write your model's behaviour in TypeScript or Python files, and bring back changes made in Arche.
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#
- Verification — Prove that your state machines and requirements hold, test with faults, and check the real system's logs.
- Why did it do that? — See a run as a timeline, follow an event back to the reading behind it, and find why something never happened.
- What proves each requirement — See, for each requirement, what satisfies it, where it is built and what proves it today.
- Safety and cybersecurity — Produce safety and security analyses straight from the model.
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.