Cyanobyte is an ongoing project which aims to define machine-readable datasheets for embedded peripheral devices. Through this, one is able to quickly generate device drivers for a given hardware platform like Arduino or Raspberry Pi.
One additional benefit is around documentation. By defining it in this way, not only can code be generated, but any type of file. In the past, LaTeX was used as the basis for generating documentation as PDFs. Now, there is a new type of output: HTML.
You can try this out with a peripheral file and version 0.0.2 of the Cyanobyte codegen from pip.
pip install cyanobyte
cyanobyte-codegen -t webpage /path/to/peripheral-file.yaml
The webpage should be located in your
build directory. It will provide a description of the peripheral and a visual table of every register.
The top of the page, and the footer, contains metadata about the peripheral and the file itself.
name: Nick Felker
description: Texas Instruments Analog-Digital Converter
name: Google Inc.
You can see each address on the left-hand side and its size. Each cell of the table includes a readable label for what it is and a more detailed description of that register. It also works for multiple fields that may be defined as one register.
Each register is defined in the
registers top-level field of a peripheral YAML file:
title: ADC Value
description: Contains the result of the last conversion
title: ADC config
description: Specifics of the sensing implementation
Here, register-level properties like being read-only can be defined.
Fields are defined in the
fields top-level attribute of the peripheral YAML file:
title: Setup sample rate for reading analog voltage
This sets the samples-per-second value
title: Setup programmable gain
This sets the programmable gain for reading analog voltage
title: Set the operating mode
This bit controls the operating mode
title: Set the channel to read
This sets the channel for reading analog voltage
Each field can have independent bit fields, names, descriptions, and I/O access. Note that in the rendered HTML output, the size of each cell corresponds to the size of the field with respect to the register.
Below this table is more information, such as any functions that may be available on the device. For this peripheral in particular, an analog-digital converter, it can convert the internal sensor value into voltage. The logic for this function is defined in machine-readable logic within the YAML file.
title: Value read from ADC
description: Reads the analog voltage in Volts
- config: '#/registers/Config'
- 0x8000 # Set single-shot mode
- raw: '#/registers/Conversion'
# Get gain from config
- programmableGain: = 6144
Adopting a machine-readable format may be a significant change to the development workflow. Developing a template for your platform may require time and engineering resources.
It may be worthwhile to explore using this format for documentation first. In doing this, you can see the benefits more quickly and improve the productivity of engineers who may still be using manually-crafted datasheets. From here, it may be more reasonable to iterate and develop a code template.
The Cyanobyte project continues to be developed on GitHub and has an open issue tracker for any issues or feature requests.