sup3legacy/arlustre

Arduino interface for the Heptagon synchronous dataflow-oriented language written in Zig.

(WIP)

Arlustre

Arduino interface for the Heptagon synchronous language written in Zig. It should provide a kinda-low-level interface to any heptagon program, through the custom Heptagon Zig backend. The whole low-level Arduino core-library is implemented using Zig. ⚠️ Only works for the standard Arduino Uno board.

Non-exhaustive list of functionning features:

• Very simple Zig backend, not extensively tested (all operations on arrays are not supported for now)
• Zig Arduino Libcore with custom bootstraping stack, interrupts, Serial, GPIO
• Interface to Heptagon for both GPIO allocation/read/write operatiosn as well as printing (more to come)

Achievements

Things I have achieved so far :

• Arduino libcore covering a not-to-bad proportion of the features available on the Arduino Uno platform (GPIO, Serial, some basic timer interrupts so far)
• Automated build using zig build
• Small Lustre interface containing GPIO-{declaration, read, write}.
• Lustre test program showing a proof-of-concept with LEDs, timers, a potentiometer and a button.

How to use

Programming

The program's main logic is located in the src/top.lus Lustre file. The interface is defined in src/interface.epi. Both files should not be moved or renamed, as the build system is quite rudimentary and assumes the existence of these files at these locations.

src/lib contains the Arduino libcore in pure Zig. It contains all basic fonctionnalities regarding MMIO, GPIO, interrupts, timers and the Serial interface. The src/libz/interrupt.zig file contains bindings to src/main.zig for the moment but this should be removed and replaced by a runtime ISR declaration during the booting process, thus making the Libz intrinsically independant from the application.

build.zig is the building script.

boot.zig is the entry point of the program. It handles both the clearing of ths .bss segment and the data-loading from Flash to RAM.

start.zig defines the main function : bootstrap where all interrupts and timers should be initialized. This function is called by _start after the booting proccess and, in this particular application, resets the state of the Lustre program.

main.zig is automatically generated but modified a bit by hand (TODO make this fully automatic) and defines global reset and step functions to drive the entire transpilled Lustre program.

top.zig is automatically generated by heptc from top.lus. It contains all the Lustre logic, i.e. the "heart of the program", everything else being only the booting process and auxiliary functions.

Prerequisites

• ocaml and some other opam libraries to compile my custom fork of heptagon (available as a submodule).
• zig version >= 0.8 (source available on Github or via some shady repackers s.a. snap or flatpak or through the AUR). Do note that Zig is still in pre-1.0 version so it tends to be not so stable now and then. If a strange behaviour is encountered, do try another (maybe more recent or more stable) release.
• screen
• avrdude
• avr-gcc for the linking process
• (optional) avr-objdump needed to use zig build objdump

How to compile

• make root directory. This should compile the modified version of heptc, run it on the test Lustre program and build the generated Zig code.
• in the src subdirectory :
  • zig heptc : runs heptc on interface.epi and top.lus and moves the generated top.zig in ./src
  • zig build : Both transpiles the Lustre program and builds the resulting Zig program into an Arduino-compatible binary
  • zig build upload : does everything mentionned before (heptc, compiles the Zig program) and uploads the program to the Arduino using a generic port using avrdude (TODO add port as an optional argument)
  • zig screen : does everything above + opens a screen session with the arduino on the same port (TODO add port as an optional argument)

Acknowledgments

Thanks to FireFox317 for their Arduino Zig basis.

Thanks to Silversquirl for their help with linker issues.