Harp.Generators

Provides a device and IO pin configuration metadata model and a set of T4 runtime templates supporting the automatic generation of firmware, Bonsai and Python interface code for Harp devices.

Installing

Installation can be done through the Harp.Generators NuGet package.

dotnet add package Harp.Generators

Editing device metadata

1. Install Visual Studio Code
2. Install the YAML extension.

The device interface can be described using a device.yml file. A complete specification of all device registers, including bit masks, group masks, and payload formats needs to be provided.

%YAML 1.1
---
# yaml-language-server: $schema=https://harp-tech.org/draft-02/schema/device.json
device: DeviceName
whoAmI: 0000
firmwareVersion: "0.1"
hardwareTargets: "0.0"
registers:
  DigitalInputs:
    address: 32
    type: U8
    access: Event

Reading device metadata

Every generator takes a DeviceMetadata object loaded from the device metadata file.

var deviceMetadata = DeviceMetadata.Load("device.yml");

Loading also checks rules that the metadata schema cannot express, and throws a YamlException listing every problem found. To read metadata from a string, use DeviceMetadata.Parse, which applies the same checks.

Generating device interface code

A complete reactive interface to communicate with the device can be generated from the device metadata.

var generator = new InterfaceGenerator(deviceMetadata, "MyNamespace");
var implementation = generator.GenerateImplementation();

Generating device firmware code

Device firmware interface stubs can be generated by providing an additional metadata file describing IO pin configuration.

var portPinMetadata = PortPinMetadata.Load("ios.yml");
var generator = new FirmwareGenerator(deviceMetadata, portPinMetadata);

var headers = generator.GenerateHeaders();
var implementation = generator.GenerateImplementation();

Generating Python interface code

An interface targeting Harp Python can be generated from the same metadata.

var generator = new PythonGenerator(deviceMetadata);
var implementation = generator.GenerateImplementation();

The generated module declares a class for every register, together with the enum and payload types they are built from, and an address to class REGISTER_MAP. Converters outside the standard set are imported from a companion converters module, written by hand alongside the generated one.

By default the implementation is generated as a single device.py module. Setting the package option generates a package initializer instead, together with a py.typed marker, so the output directory alone determines the import path.

var generator = new PythonGenerator(deviceMetadata, package: true);
var implementation = generator.GenerateImplementation();

Writing that implementation into src/mypackage/mydevice produces the mypackage.mydevice package, with the companion converters module beside it in the same directory.

Generating register documentation

Language-neutral reference documentation for the register interface can be generated for a DocFX site.

var generator = new DocumentationGenerator(deviceMetadata, "MyNamespace");
var implementation = generator.GenerateImplementation();

The implementation holds a table of contents and a UniversalReference page for each public register, payload type and mask, listing the C# and Python names of the type and its members. The namespace must match the one passed to InterfaceGenerator, since every page targets the UID of a generated type.

Register details such as address and access are stored in a harp property of each page. Displaying them requires a custom DocFX template.

Contributing

Bug reports and contributions are welcome at the GitHub repository.

License

Harp.Generators is released as open-source under the MIT license.