EpoxyDuino

This project contains a small (but often effective) implementation of the Arduino programming framework for Linux, MacOS, FreeBSD (experimental) and potentially other POSIX-like systems. Originally, it was created to allow AUnit unit tests to be compiled and run on a desktop class machine, instead of running on the embedded microcontroller. As more Arduino functionality was added, I found it useful for doing certain types of application development on my Linux laptop, especially the parts that were more algorithmic instead of hardware dependent. EpoxyDuino can be effectively used in Continuous Integration (CI) pipeline (like GitHub Actions) for automatically validating that a library or application compiles without errors.

The build process uses GNU Make. A simple Makefile needs to be created inside the sketch folder. For example, if the sketch is SampleTest/SampleTest.ino, then the makefile should be SampleTest/Makefile. The sketch is compiled with just a make command. It produces an executable with a .out extension, for example, SampleTest.out.

The Serial port object sends the output to the STDOUT and reads from the STDIN of the Unix host environment. Most other hardware dependent features (e.g. I2C, SPI, GPIO) are stubbed out (defined but don't do anything) to allow the Arduino programs to compile. Mock versions of various libraries are also provided:

• <Wire.h>: mock I2C library
• <SPI.h>: mock SPI library
• EpoxyMockDigitalWriteFast: mock version of the digitalWriteFast libraries
• EpoxyMockTimerOne: mock version of the TimerOne (https://github.com/PaulStoffregen/TimerOne) library
• EpoxyMockFastLED: mock version of the FastLED (https://github.com/FastLED/FastLED) library
• EpoxyMockSTM32RTC: mock version of the STM32RTC (https://github.com/stm32duino/STM32RTC) library

These mock libraries may be sufficient for a CI pipeline.

For actual application development, I have started to build a set of libraries within EpoxyDuino which emulate the versions that run the actual hardware:

• EpoxyFS: emulation of the ESP8266 LittleFS or ESP32 LittleFS filesystem
• EpoxyEepromAvr: emulation of AVR-flavored EEPROM
• EpoxyEepromEsp: emulation of ESP-flavored EEPROM

If your program has limited hardware dependencies so that it is conceptually portable to a vanilla Unix environment, EpoxyDuino may work well for you.

Running an Arduino program natively on a desktop-class machine has some advantages:

• The development cycle can be lot faster because the compilers on the desktop machines are a lot faster, and we also avoid the upload and flash process to the microcontroller.
• The desktop machine can run unit tests which require too much flash or too much memory to fit inside an embedded microcontroller.
• It may help you write platform-independent code, because if it runs under EpoxyDuino, it has a good chance of running on most Arduino-compatible platforms.

The disadvantages are:

• Only a subset of Arduino functions are supported (see below).
• Many 3rd party libraries will not compile under EpoxyDuino.
• There may be compiler differences between the desktop and the embedded environments (e.g. 16-bit int versus 32-bit int, or 32-bit long versus 64-bit long).

Version: 1.6.0 (2024-07-25)

Changelog: See CHANGELOG.md

Table of Contents

• Installation
• Usage
  • Makefile
  • Additional Arduino Libraries
  • Additional Arduino Library Locations
  • Difference from Arduino IDE
  • Conditional Code
  • Managing Multiple Makefiles
  • Continuous Integration
• Advanced Usage
  • Alternate C++ Compiler
  • Additional Cpp Flags
  • Additional Compiler Flags
  • Additional Clean Up
  • Additional Dependencies
  • Generated Source Code
  • Alternate Arduino Core
  • PlatformIO
  • Command Line Flags and Arguments
  • Termination
  • Debugging
    • Valgrind
  • Mock digitalRead() digitalWrite()
    • digitalReadValue()
    • digitalWriteValue()
• Supported Arduino Features
  • Arduino Functions
  • Serial Port Emulation
    • Unix Line Mode
    • Enable Terminal Echo
    • Output to STDERR
    • Multiple Serial Ports
    • Shell Redirection
• Libraries and Mocks
  • Inherently Compatible Libraries
  • Emulation Libraries
  • Mock Libraries
• System Requirements
• License
• Bugs And Limitations
• Feedback and Support
• Authors

<a name="Installation"></a>

Installation

You need to grab the sources directly from GitHub. This project is not an Arduino library so it is not available through the Arduino Library Manager in the Arduino IDE.

The location of the EpoxyDuino directory can be arbitrary, but a convenient location might be the same ./libraries/ directory used by the Arduino IDE to store other Arduino libraries:

$ cd {sketchbook_directory}/libraries
$ git clone https://github.com/bxparks/EpoxyDuino.git

This will create a directory called {sketchbook_directory}/libraries/EpoxyDuino, and put you on the default develop branch.

You can be slightly conservative and use the latest stable release on the master branch:

$ cd {sketchbook_directory}/libraries/EpoxyDuino
$ git checkout master

You can go to a specific release by checking out the corresponding tag, for example v1.2.0:

$ git checkout v1.2.0

Dependencies

The core of EpoxyDuino depends on:

• a C++ compiler (g++ or clang++)
• GNU Make (usually make but sometimes gmake)

These are normally installed on the host OS by default.

The example and test code under ./tests/, ./examples/, ./libraries/*/tests/, and ./libraries/*/examples/ depend on:

• AUnit (https://github.com/bxparks/AUnit)
• AceCRC (https://github.com/bxparks/AceCRC)
• AceCommon (https://github.com/bxparks/AceCommon)
• AceRoutine (https://github.com/bxparks/AceRoutine)
• AceUtils (https://github.com/bxparks/AceUtils)

<a name="Usage"></a>

Usage

<a name="Makefile"></a>

Makefile

The minimal Makefile has 3 lines:

APP_NAME := {name of project}
ARDUINO_LIBS := {list of dependent Arduino libraries}
include {path/to/EpoxyDuino.mk}

For example, the examples/BlinkSOS project contains this Makefile:

APP_NAME := BlinkSOS
ARDUINO_LIBS :=
include ../../../EpoxyDuino/EpoxyDuino.mk

To build the program, just run make:

$ cd examples/BlinkSOS
$ make clean
$ make

The executable will be created with a .out extension. To run it, type one of the following:

$ ./BlinkSOS.out
$ make run

If you run :make run command inside the vim editor, it knows how to parse the file and line number contained in the assertion messages generated by AUnit. The vim editor will jump directly to the file and line where the assertion failure occurred. See https://vimhelp.org/quickfix.txt.html for information on the quickfix feature and the errorformat format that parses the GNU Make output.

The output that would normally be printed on the Serial on an Arduino board will be sent to the STDOUT of the Linux, MacOS, or FreeBSD terminal. The output should be identical to what would be shown on the serial port of the Arduino controller.

<a name="AdditionalLibraries"></a>

Additional Arduino Libraries

If the Arduino program depends on additional Arduino libraries, they must be specified in the Makefile using the ARDUINO_LIBS parameter. For example, the following includes the AUnit, AceButton, and AceTime libraries if they are installed at the same directory level as EpoxyDuino:

APP_NAME := SampleTest
ARDUINO_LIBS := AUnit AceButton AceTime
include ../../EpoxyDuino/EpoxyDuino.mk

The libraries are referred to using their base directory name (e.g. AceButton, or AceTime) not their full path. By default, the EpoxyDuino.mk file will look for these additional libraries at the following locations:

• EPOXY_DUINO_DIR/../ - in other words, siblings to the EpoxyDuino install directory (this assumes that EpoxyDuino was installed in the Arduino libraries directory as recommended above)
• EPOXY_DUINO_DIR/libraries/ - additional libraries provided by the EpoxyDuino project itself
• under each of the additional directories listed in ARDUINO_LIB_DIRS (see below)

Version v1.5 supports compiling and linking plain C files