Firmware Docs¶

Elara's laser operates semi-autonomously due to environmental constraints (as it can only run in vacuum) and safety reasons (due to electron beam radiation, UV light, and other hazards present in the laser). It uses an Arduino Uno as its microcontroller (basically a mini-computer). This page describes the firmware that runs on the microcontroller.

Prerequisites¶

The rest of this page assumes that you already have the Elara laser repository available on your system and that you are in the Firmware/ folder of the repository. You will also need the Arduino IDE or Arduino CLI, as well as some knowledge of C++ and of embedded development. If not, please review the chapters on C++ programming and embedded development on the Elara Handbook.

We include the DHT11 temperature & humidity sensor library in the libraries/DHT folder (a more recent version is also available but may not be compatible). This folder must be manually added in the Arduino IDE. Please reference the relevant Arduino IDE docs explaining how to do so.

Building¶

There are two ways to build, depending on your choice of build system:

Using the CLI, the build flags are pre-configured, so you can just build with ./build.sh and upload with ./upload.sh [port].

Using the Arduino IDE, set your build flags to -Wall -Werror -Wextra (-Werror treats all warnings as errors). For Arduino Uno, you will need to go to %AppData%\Local\Arduino15\packages\arduino\hardware\avr\[version]\platform.txt. Open platform.txt in a text editor and add -Werror to compiler.warning_flags.all=-Wall -Wextra. Restart the IDE and go to File > Preferences and set Compiler warnings to All.

Info¶

The arduino firmware provides the following commands:

• COMMAND_INFO: Obtain hardware information string.
• COMMAND_RESET: Perform soft reset.
• COMMAND_ERROR_CODE: Retrieve error code.

Currently, the default template implements one error code, that is "ERR_COMMAND_NOT_FOUND", which is set in case an undefined command was called.

Development¶

Before developing you must set up pre-commit. Once it is installed run pre-commit install from the root laser-research directory. This will set up our auto-formatting enforcement. Also, please setup the Cobra static analyzer following these instructions to ensure your code conforms to our safety standards.

Please be aware that since the electron gun in the laser is a source of ionizing radiation and thus a potential safety hazard, code for the laser must adhere to strict coding standards. In particular, C/C++ code must obey the power of ten rules:

1. Write with simple control flow, meaning no goto, setjmp, longjmp and no recursion
2. Loops must clearly terminate after a fixed number of iterations to avoid infinite loops
3. Do not use dynamic memory allocation (e.g. malloc) after the system is initialized
4. Do not write excessively-long functions: specifically, each function should not exceed 60 lines of code
5. Assume that inputs can have invalid, unexpected, or corrupted data; in any function, there should be at least two validation checks (preferably more) of input data
6. Avoid using scoped variables, as they can "disappear" if they go out of scope
7. Anything returned by a function must be checked whenever the function is called. While this is not an explicit rule, avoid using exceptions when programming in C++ since an unhandled exception poses major risks
8. Use the C/C++ preprocessor as simply as possible; that is, do not put in preprocessor hacks, complicated macros, metaprogramming constructs, or anything else involving non-obvious preprocessor logic
9. Use pointers carefully; a pointer should never point to another pointer. Do not use macros or typedef's for dereferencing a pointer
10. All code must be compiled from the start of the development process with all compiler warnings enabled at the most pedantic setting possible, and checked with a static checker (we specifically use Cobra from NASA's JPL)

Any deviations from the rules must be followed with an explicit explanation justifying why the specific case required breaking the rules. We take safety very seriously! For more:

• Power of Ten Rules
• NASA JPL C coding standard
• JSF coding standard
• Some videos on programming for safety-critical systems:
  • C++ coding requirements for flight software
  • How NASA writes space-proof code

Simulating¶

You can use PICSimLab to simulate an Arduino uno to test your changes on.

Installation¶

Go to their releases page and download and install the version for your operating system. (Linux and Windows are supported, Mac requires Wine.)

Next, install a NULL-MODEM emulator. This allows you to upload to the simulated board from the Arduino CLI or IDE. Follow these instructions.

Finally, load the Arduino bootloader. (In PICSimLab, go to Tools > Arduino bootloader). Then to upload, set the Arduino port to COM2 (Windows) or /dev/tnt3 (Linux) and it should be all set.