Welcome to BitstreamEvolution’s Documentation!#
This is the develop branch documentation for BitstreamEvolution.
Warning
This is the development documentation for the develop branch, which is
actively being worked on by developers. It may contain incomplete features,
experimental content, or issues not present on the
stable release site.
This site also includes TODO items and development notes that are hidden on the release website. If you are looking for stable documentation, please visit the release site linked above.
Note
Currently we are trying to do a rewrite of the main repository to use new interfaces to make the codebase more modular.
Until this is done, the develop branch will be used for this process and modifications will be made to the main branch directly for pre-existing code.
Installation, prerequisites, and running your first experiment.
System design, hardware model, and protocol specifications.
Protocol interfaces, implementations, and auto-generated module docs.
Build instructions, test results, and contribution information.
The Evolvable Hardware Community#
BitstreamEvolution is one project developed by the Evolvable Hardware research group, which explores the use of evolutionary computation on physical hardware. Visit the community website to learn about other projects and ongoing research in this space.
Evolvable Hardware Community Website
Indices and tables#
To Do List#
Todo
This documentation was drafted from code analysis and needs verification against hardware datasheets.
(The original entry is located in /home/runner/work/BitstreamEvolution/BitstreamEvolution/develop/docs/sphinx/source/architecture/hardware/ice40_hardware.rst, line 4.)
Todo
Verify tile coordinate ranges against hardware datasheets. The ranges below
are hard-coded in FileBasedCircuit.__tile_is_included and are specific to
the ICE40 HX1K. A different iCE40 model (e.g., HX8K) would require
different ranges.
(The original entry is located in /home/runner/work/BitstreamEvolution/BitstreamEvolution/develop/docs/sphinx/source/architecture/hardware/ice40_hardware.rst, line 90.)
Todo
Verify routing row selections against hardware datasheets. The row selections below are noted in the source as “dated” and may not reflect the latest routing protocol.
(The original entry is located in /home/runner/work/BitstreamEvolution/BitstreamEvolution/develop/docs/sphinx/source/architecture/hardware/ice40_hardware.rst, line 117.)
Todo
This documentation was drafted from code analysis and needs verification against the MCU firmware.
(The original entry is located in /home/runner/work/BitstreamEvolution/BitstreamEvolution/develop/docs/sphinx/source/architecture/hardware/mcu_protocol.rst, line 4.)
Todo
Verify waveform protocol against the MCU firmware. The exact sample count, sample rate, and ADC resolution should be confirmed with the firmware source.
(The original entry is located in /home/runner/work/BitstreamEvolution/BitstreamEvolution/develop/docs/sphinx/source/architecture/hardware/mcu_protocol.rst, line 90.)
Todo
Verify pulse count protocol against the MCU firmware. The pulse-counting window duration and any firmware-side filtering should be confirmed with the firmware source.
(The original entry is located in /home/runner/work/BitstreamEvolution/BitstreamEvolution/develop/docs/sphinx/source/architecture/hardware/mcu_protocol.rst, line 126.)
Todo
Optimize serial read/write in measure_signal — the waveform reading loop
could read all available bytes at once rather than line-by-line.
(The original entry is located in /home/runner/work/BitstreamEvolution/BitstreamEvolution/develop/docs/sphinx/source/architecture/hardware/mcu_protocol.rst, line 195.)
Todo
Improve regex/filtering in measure_pulses_once — the current chain of
byte-string containment checks should be replaced with a proper parser that
handles transmission-loss artefacts (dropped or extra spaces, shifted colons).
(The original entry is located in /home/runner/work/BitstreamEvolution/BitstreamEvolution/develop/docs/sphinx/source/architecture/hardware/mcu_protocol.rst, line 200.)
Todo
Add elif branches in request_measurement() to handle future
DataRequest types beyond WAVEFORM and OSCILLATIONS.
(The original entry is located in /home/runner/work/BitstreamEvolution/BitstreamEvolution/develop/docs/sphinx/source/architecture/hardware/mcu_protocol.rst, line 206.)
Todo
Figure out the format for an FPGA Request, potentially also changing the type, and adjust that here.
(The original entry is located in /home/runner/work/BitstreamEvolution/BitstreamEvolution/develop/src/BitstreamEvolutionProtocols.py:docstring of BitstreamEvolutionProtocols.Measurement.__init__, line 1.)
Todo
Expand this section with detailed test-writing guidance: fixture patterns,
when to use tmp_path vs monkeypatch, how to handle hardware-dependent
tests, and worked examples for each protocol.
(The original entry is located in /home/runner/work/BitstreamEvolution/BitstreamEvolution/develop/docs/sphinx/source/dev/contributing.rst, line 132.)
Important
Todo lists only appear if enabled. They will not be enabled on the main website, only develop.
To do this, run: sphinx-build -M html source build -t dev