baldaquin.arduino_ — Arduino interface#

This module provides minimal support for interacting with the Arduino ecosystem, the basic idea is that we start with Arduino UNO and we add on more boards as we need them.

See also

In order to fully utilize the facilities in this module you will need at least some additional third-paryt software. The following links are relevant for operating with Arduino boards.

Since nowadays the Arduino CLI seems to be the preferred way to interact programmatically with the Arduino ecosystem, we will assume that is the default choice. If you have arduino-cli installed you should be good to go—see the installation instructions. (This will literally run a script and copy the executable on your machine, which is handy because you will not need administrator priviledges to run the thing. The same thing holds for all the additional modules, e.g., arduino:avr you might need.)

The ArduinoBoard class provides a small container encapsulating all the information we need to interact with a board, most notably the list of DeviceId for the latter (that can be used to auto-detect boards attached to a COM port), as well as the relevant parameters to upload sketches on it.

A small database internal to the class contains a list of boards that we support, and which can be retrieved either by DeviceId or by designator:

>>> board = ArduinoBoard.by_device_id(DeviceId(0x2341, 0x43))
>>> print(board)
ArduinoBoard(designator='uno', name='Arduino UNO', vendor='arduino',
    architecture='avr', upload_protocol='arduino', upload_speed=115200,
    build_mcu='atmega328p', device_ids=((vid=0x2341, pid=0x43),
    (vid=0x2341, pid=0x1), (vid=0x2a03, pid=0x43), (vid=0x2341, pid=0x243),
    (vid=0x2341, pid=0x6a)))
>>>
>>> board = ArduinoBoard.by_designator('uno')
>>> print(board)
ArduinoBoard(designator='uno', name='Arduino UNO', vendor='arduino',
    architecture='avr', upload_protocol='arduino', upload_speed=115200,
    build_mcu='atmega328p', device_ids=((vid=0x2341, pid=0x43),
    (vid=0x2341, pid=0x1), (vid=0x2a03, pid=0x43), (vid=0x2341, pid=0x243),
    (vid=0x2341, pid=0x6a)))

Auto-detecting boards#

The module comes with a couple of utilities to help auto-detecting boards.

autodetect_arduino_boards() will look over all the COM ports and identify all the supported Arduino boards connected. An arbitrary number of board objects can be passed to the function, and they will act as a filter for the boards that are actually returned. If, e.g., you are interested in all the Arduino UNOs connected, you can do something along the lines of:

>>> ports = arduino_.autodetect_arduino_boards(arduino_.UNO)
>>> [INFO] Autodetecting Arduino boards ['Arduino UNO']...
>>> [INFO] Scanning serial devices...
>>> [DEBUG] Port(name='/dev/ttyS0', device_id=(vid=None, pid=None), manufacturer=None)
>>> [DEBUG] Port(name='/dev/ttyACM0', device_id=(vid=0x2341, pid=0x43), manufacturer='Arduino (www.arduino.cc)')
>>> [INFO] Done, 2 device(s) found.
>>> [INFO] Filtering port list for specific devices: [(vid=0x2341, pid=0x43), (vid=0x2341, pid=0x1), (vid=0x2a03, pid=0x43), (vid=0x2341, pid=0x243), (vid=0x2341, pid=0x6a)]...
>>> [INFO] Done, 1 device(s) remaining.
>>> [DEBUG] Port(name='/dev/ttyACM0', device_id=(vid=0x2341, pid=0x43), manufacturer='Arduino (www.arduino.cc)')
>>> [DEBUG] /dev/ttyACM0 -> uno (Arduino UNO)
>>>
>>> print(ports)
>>> [Port(name='/dev/ttyACM0', device_id=(vid=0x2341, pid=0x43), manufacturer='Arduino (www.arduino.cc)')]

The function returns a list of Port objects, that are ready to use.

In many cases you might be interested in a single board, in which case you can use the autodetect_arduino_board(), variant. This will return the first board that is found, and log a warning if more than one is connected.

These two functions can be integrated in complex workflows as needed.

Uploading sketches#

This module implements two diffent interfaces to programmatically upload sketches onto a connected Arduino board:

  • ArduinoCli, wrapping the Arduino command-line interface;

  • AvrDude, wrapping avrdude.

As already said earlier on, we shall assume that arduino-cli is the preferred way to do business. In most cases you can simply use the top-level interface upload_sketch() to upload a sketch onto an Arduino board connected to the computer.

The baldaquin command-line interface provides a target to manually compile a sketch to an arduino board

[lbaldini@nblbaldini baldaquin]$ python baldaquin/cli.py arduino-upload --help
usage: cli.py arduino-upload [-h] [--board-designator BOARD_DESIGNATOR]
                             file_path

positional arguments:
  file_path             the path to the compiled sketch file

options:
  -h, --help            show this help message and exit
  --board-designator BOARD_DESIGNATOR

Compiling sketches#

The module also provides a way to compile sketches, using the simple, top-level interface compile_sketch().

The baldaquin command-line interface provides a target to manually compile a sketch to an arduino board

[lbaldini@nblbaldini baldaquin]$ python baldaquin/cli.py arduino-compile --help
usage: cli.py arduino-compile [-h] [--output_dir OUTPUT_DIR]
                              [--board_designator BOARD_DESIGNATOR]
                              file_path

positional arguments:
  file_path             the path to the sketch source file

options:
  -h, --help            show this help message and exit
  --output_dir OUTPUT_DIR
  --board_designator BOARD_DESIGNATOR

Note that, depending on the particular sketch you are trying to compile, you might need additional external library not bundled in the initial ArduinoCli installation. You find all the necessary resources about libraries in arduino at the docs page, but in a nutshell, you can search for specific libraries by doing

[lbaldini@nblbaldini baldaquin]$ arduino-cli lib search HTS221
Name: "Adafruit HTS221"
  Author: Adafruit
  Maintainer: Adafruit <info@adafruit.com>
  Sentence: Arduino library for the HTS221 sensors in the Adafruit shop
  Paragraph: Arduino library for the HTS221 sensors in the Adafruit shop
  Website: https://github.com/adafruit/Adafruit_HTS221
  Category: Sensors
  Architecture: *
  Types: Contributed
  Versions: [0.1.0, 0.1.1, 0.1.2, 0.1.4, 0.1.5]
  Dependencies: Adafruit Unified Sensor, Adafruit BusIO
Name: "Arduino_HTS221"
  Author: Arduino
  Maintainer: Arduino <info@arduino.cc>
  Sentence: Allows you to read the temperature and humidity sensors of your Nano 33 BLE Sense.
  Paragraph:
  Website: http://github.com/arduino-libraries/Arduino_HTS221
  Category: Sensors
  Architecture: *
  Types: Arduino
  Versions: [1.0.0]
  Provides includes: Arduino_HTS221.h
Name: "FaBo 208 Humidity HTS221"
  Author: FaBo<info@fabo.io>
  Maintainer: Akira Sasaki<akira@fabo.io>
  Sentence: A library for FaBo Humidity I2C Brick
  Paragraph: HTS221 is humidity and temperature sensor.
  Website: https://github.com/FaBoPlatform/FaBoHumidity-HTS221-Library
  Category: Sensors
  Architecture: avr
  Types: Contributed
  Versions: [1.0.0]
Name: "STM32duino HTS221"
  Author: AST, Wi6Labs
  Maintainer: stm32duino
  Sentence: Capacitive digital sensor for relative humidity and temperature.
  Paragraph: This library provides Arduino support for the capacitive digital sensor for relative humidity and temperature HTS221 for STM32 boards.
  Website: https://github.com/stm32duino/HTS221
  Category: Sensors
  Architecture: *
  Types: Contributed
  Versions: [1.0.1, 1.0.2, 1.0.3, 1.0.4, 2.0.0, 2.0.1]
Name: "SmartEverything HTS221"
  Author: Seve
  Maintainer: axelelettronica <development@axelelettronica.it>
  Sentence: Library code for HTS221 Capacitive digital sensor for relative humidity and temperature
  Paragraph: The HTS221 is an ultra compact sensor for relative humidity and temperature.<br>It includes a sensing element and a mixed signal ASIC to provide the measurement information through digital serial interfaces.<br>The sensing element consists of a polymer dielectric planar capacitor structure capable of detecting relative humidity variations and is manufactured using a dedicated ST process.<br>The HTS221 is available in a small top-holed cap land grid array (HLGA) package guaranteed to operate over a temperature range from -40 °C to +120 °C.
  Website: https://github.com/ameltech/sme-hts221-library
  Category: Sensors
  Architecture: *
  Types: Contributed
  Versions: [1.0.0, 1.1.0, 1.1.1, 1.1.2]
Name: "Sodaq_HTS221"
  Author: Alex Tsamakos,SODAQ
  Maintainer: Alex Tsamakos,SODAQ
  Sentence: An Arduino library for the HTS221 sensor.
  Paragraph: Supports humidity and temperature sensors.
  Website: https://github.com/SodaqMoja/Sodaq_HTS221
  Category: Sensors
  Architecture: *
  Types: Contributed
  Versions: [1.0.0]

and then install the one that you need via

[lbaldini@nblbaldini baldaquin]$ arduino-cli lib install "STM32duino HTS221"
Downloading STM32duino HTS221@2.0.1...
STM32duino HTS221@2.0.1 downloaded
Installing STM32duino HTS221@2.0.1...
Installed STM32duino HTS221@2.0.1

Module documentation#