Appendix A — Development Environment
In the interest of reducing the pedagogic friction arising out of the diverse computing platforms, this book comes with a pre-configured development environment. The development environment is available as Docker images, and can be used on any platform that supports Docker.
The application build image includes the GNAT Ada compiler, the Alire package manager, and all the tools and libraries needed to follow along with the examples in this book. The file Dockerfile.native found in the devops repository builds the container image and is available at container image
The later projects in this book generate data streams that can be captured and analyzed. The data analysis environment is available as a container image built with the Dockerfile found in the dataops repository and is available at container image Julia is the primary data analysis environment used in this book.
The documentation build image built with Dockerfile found in the docops repository builds a container image with quarto and is available at container image
The book is produced with these containers in a CI pipeline.
A.1 Application code repository
https://gitlab.com/ada23/embedded/stm32f4disco/projects.git serves as the application code repository. Divided into a series of projects of increasing functionality and complexity. It uses the Ada Drivers Library as a submodule. It is designed to be collaborative with other components but can be used independently as well.
Each project eg. cli contains the source code, build, and flash support as well as documentation. The documentation is designed to be integrated with the book but can be built and viewed independently. Typicall the documentation includes extracts from the source code for illustrative purposes.
A.1.1 Book source
The directory 99_doc contains the documentation structure. quarto is the documentation engine used.
A.1.2 Target microcontrollers
The conceptual framework utilitizes the STM32f4 Discovery board as the target microcontroller. Versions of this book and the accompanying code are planned for the ESP32 and the Raspberry Pi Pico.
A.1.3 Usage
The containers have ssh servers running and can be accessed using ssh. The containers are configured to listen on different ports on the host machine:
| Container | ssh port |
|---|---|
| devops:latest | 2222 |
| docops:latest | 2223 |
| dataops:latest | 2224 |
A.1.4 Building the applications
The container devops:latest is used for building the applications. The shared volume is mounted at /ws in the container. A script buildall.py may be provided by the application to build the example applications.
cd /ws/projects
python3 buildall.pyA.1.5 Code deployment or flashing the target
If the host is Linux, the binaries may also be downloaded to the target using the tools in the container such as openocd and st-flash. Other platforms such as Windows and MacOs may not support direct download from the container and will rely on the host versions of these tools. Typically each project has a script flash.sh that can be used to flash the target using openocd.
A.1.6 Code example extracts
In addition to the binaries of the application, the container also can generate code extracts that are used in the documentation. These code extracts are generated using the codemd tool and are made available to the documentation container through the shared volume. For instance:
codemd -D./.codemd src/*.ad*will analyze all the ada files, extract the designated segments and deposit them in the .codemd directory.
The script pushdoc.py pushes all the documentation including code extracts in .codemd in the source code repository to the documentation environment prior to building the book.
A.1.7 Building the documentation
The container docops:latest is used for building the documentation. The book source is made available to the container at /ws/doc and the output is typically available at /ws/doc/public. :
cd /ws/doc/src
quarto renderA.1.8 Data Analysis
Most of the applications in this book generate data streams that can be captured and analyzed using the documentation container. Julia is the primary data analysis environment used in this book and is available in the container dataops:latest.