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

Generating device interface code

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

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

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

Load also accepts a TextReader, and Parse reads device metadata from a string, such as the embedded metadata exposed by a generated interface through Device.Metadata. Both methods resolve the YAML merge keys that make schema reuse possible, so device metadata should always be read with one of them.

Generating device firmware code

Assuming the deviceMetadata object loaded above is available, 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

Assuming the deviceMetadata object loaded above is available, 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.

Contributing

Bug reports and contributions are welcome at the GitHub repository.

License

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