dmf-control-board-firmware

Firmware for an Arduino-based DMF control board and a Python module for communicating with it over a serial connection.

Table of Contents generated with DocToc

• Install
• Conda package contents
• Build Conda package (including firmware and host driver)
• Develop
  • Set up development environment (within a Conda environment)
  • Build firmware
  • Flash/upload firmware
  • Build host driver (Python C-extension)
  • Unlink development working copy
• Contributors

Install

The latest dmf-control-board-firmware release is available as a Conda package from the wheeler-microfluidics channel using.

To install dmf-control-board-firmware in a Conda environment, run:

conda install -c wheeler-microfluidics -c conda-forge dmf-control-board-firmware

Conda package contents

The dmf_control_board_firmware Conda package includes:

• A low-level host driver (written in C++) for communicating with the control board over a serial interface (exposed to Python through Boost Python bindings).
• A dmf_control_board_firmware.DMFControlBoard Python class providing a high-level wrapper around the Boost Python bindings C++ API.
• Compiled firmware binaries for each control board hardware revision.

The installed components (relative to the root of the Conda environment) are shown below:

├───Lib
│   └───site-packages
│       └───dmf_control_board_firmware (Python package including host driver)
│           │   ...
│           │   dmf_control_board_base.pyd
│           │   libboost_python-mgw44-mt-1_46_1.dll
│           │   mingwm10.dll
│           │   ...
│
└───Library
    └───bin
        └───platformio
            └───dmf-control-board-firmware (compiled firmware binaries)
                │   platformio.ini   (PlatformIO environment information)
                │
                ├───mega2560_hw_v1_1
                │       firmware.hex
                │
                ├───mega2560_hw_v1_2
                │       firmware.hex
                │
                ├───mega2560_hw_v1_3
                │       firmware.hex
                │
                ├───mega2560_hw_v2_0
                │       firmware.hex
                │
                └───mega2560_hw_v2_1
                        firmware.hex

Build Conda package (including firmware and host driver)

Install conda-build:

conda install conda-build

Build Conda package (including firmware binaries and host C-extension driver) from included recipe:

conda build .conda-recipe

(Optional) Install built Conda package (including control board firmware and host C-extension driver):

conda install -c wheeler-microfluidics -c conda-forge --use-local dmf-control-board-firmware

Develop

Set up development environment (within a Conda environment)

1. Clone dmf-control-board-firmware source code from GitHub repository.

2. Install development dependencies (including dependencies required for paver develop_link command in 3):

   conda install -c wheeler-microfluidics -c conda-forge dmf-control-board-firmware-develop

3. Run the following command within the root of the cloned repository to install run-time dependencies and link working copy of firmware binaries and Python package for run-time use:

   paver develop_link

4. Restart terminal and reactivate Conda environment (e.g., activate if Conda was installed with default settings).

Step 4 is necessary since at least one of the installed dependencies sets environment variables, which are only initialized on subsequent activations of the Conda environment (i.e., they do not take effect immediately within the running environment).

Build firmware

Run the following command within the root of the cloned repository to build the firmware (host driver .pyd/.dll files will not be built):

paver build_firmware

N.B., the paver build_firmware command will build a separate firmware binary for each hardware environment listed in the platformio.ini file (e.g., mega2560_hw_v1_1, mega2560_hw_v2_1).

The compiled firmware binaries are available under the .pioenvs directory, as shown below:

└───.pioenvs
    ├───mega2560_hw_v1_1
    │       firmware.hex
    │
    ├───mega2560_hw_v1_2
    │       firmware.hex
    │
    ├───mega2560_hw_v1_3
    │       firmware.hex
    │
    ├───mega2560_hw_v2_0
    │       firmware.hex
    │
    └───mega2560_hw_v2_1
            firmware.hex

Flash/upload firmware

To flash/upload a compiled firmware to a connected Arduino Mega2560 board, run the following command from the root of the repository:

pio run --target upload --target nobuild -e <hardware environment> --upload-port <COM port>

replacing:

• <hardware environment> with the tag corresponding to the control board hardware version (e.g., mega2560_hw_v2_1)
• <COM port> with the serial port corresponding to the connected control board Arduino Mega2560 (e.g., COM1)

Build host driver (Python C-extension)

The low-level host driver for communicating with the control board over a serial interface is written in C++ and exposing a Python API through Boost Python bindings.

N.B., the dmf_control_board_firmware.DMFControlBoard Python class provides a high-level wrapper around the C++ class API.

Run the following command within the root of the cloned repository to build the Boost Python bindings (i.e., .pyd/.dll files):

scons

Unlink development working copy

Run the following command within the root of the cloned repository to unlink working copy of firmware binaries and Python package:

paver develop_unlink

This will allow, for example, installation of a main-line release of the dmf-control-board-firmware Conda package.

Contributors

• Ryan Fobel (@ryanfobel)
• Christian Fobel (@cfobel)