From Gentoo Wiki
Jump to:navigation Jump to:search

Arduino is an open source development platform.

This article describes the process of configuring a Gentoo system to connect to an Arduino, the installation of a cross-development toolchain, and the installation of the Arduino IDE.

In addition to both official and clone Arduino boards based on Atmel AVR microprocessors, the environment can support other Atmel AVR microprocessors including, but not limited to: ATtiny13 microprocessors, nRF52 SoCs, and STM32 microprocessors.

Prepare the kernel for USB connection

Arduino boards are connected to a computer via USB. With this connection it is possible to send compiled binaries "sketches" to the Arduino's microprocessor and receive debug messages from the board during execution. Each model of board features a different USB interface chip; consult the board's documentation if unsure about the USB interface in use. Check dmesg output as well for hints about the USB interface.

If in-system programming with an external programmer is preferred the Arduino IDE is not required for programming the device, however it may still be required to receive debugging output.

In order to support Arduino devices the appropriate kernel driver must be enabled; it may be built into the kernel or as a module.

Arduino NG (FTDI)

KERNEL FTDI interface
Device Drivers  --->
    [*] USB support ---> 
      <*> USB Serial Converter support --->
        <*> USB FTDI Single Port Serial Driver

Arduino MEGA, UNO, Atmega8U2, Atmega16U2, Atmega32U4, Zero (CDC ACM)

Device Drivers  --->
    [*] USB support ---> 
      <*> USB Modem (CDC ACM) support

Arduino NANO (CH340)

This series of boards has included a range of serial converter chips, however the most commonly used is the CH340.

KERNEL CH340 serial converter
Device Drivers  --->
    [*] USB support ---> 
      <*> USB Serial Converter support --->
        <*> USB Winchiphead CH341 Single Port Serial Driver

Arduino ESP32 (CP210)

KERNEL CH340 serial converter
Device Drivers  --->
    [*] USB support ---> 
      <*> USB Serial Converter support --->
        <*> USB CP210x family of UART Bridge Controllers

Validate connectivity

After support for the device has been enabled, and the computer rebooted if necessary, connectivity to the board must be validated: connect the Arduino to an available USB port then check for messages in the kernel ring buffer:

For an Arduino NG:

root #dmesg
usb 5-4: FTDI USB Serial Device converter now attached to ttyUSB0

For an Arduino MEGA:

root #dmesg
cdc_acm 5-4:1.0: ttyACM0: USB ACM device

For an Arduino ESP32:

root #dmesg
usb 3-11: cp210x converter now attached to ttyUSB0

Grant access to non-root users

Any non-root user that wishes to connect to the device should be added to the dialout group, as the device's file (e.g. /dev/ttyACM0) is owned by that group.

To add Larry to the group run the following command:

root #gpasswd -a larry dialout
Larry will need to log off and back on before permissions granted by the group will take effect, until then he will be unable to access the device

Prepare the toolchain

As Atmel AVR microprocessors require different compiled output from the development platform (most often x86-64) a cross development toolchain must be installed.

Recommended: Install the toolchain using crossdev

This section provides condensed instructions for creating a cross-compiler, originally found in the Embedded Handbook. Consult the handbook for an introduction to crossdev and its operation.

Installing crossdev

Install sys-devel/crossdev:

root #emerge --ask sys-devel/crossdev
If issues are encountered installing crossdev, try unmasking a more recent (unstable) version.

Create an ebuild repository locally

Before the local toolchain can be built, an ebuild repository called crossdev must be created locally.

The crossdev ebuild repository will be automatically selected by the crossdev tool to build packages for all crossdev-targeted platforms — creating this ebuild repository will ensure that all of the crossdev built packages remain completely separate from native packages on the development system.
These commands are a condensed form of the instructions available on the creating an ebuild repository article, which has more detailed information.
root #mkdir -p /var/db/repos/portage-crossdev/{profiles,metadata}
root #echo 'crossdev' > /var/db/repos/portage-crossdev/profiles/repo_name
root #echo 'masters = gentoo' > /var/db/repos/portage-crossdev/metadata/layout.conf
root #chown -R portage:portage /var/db/repos/portage-crossdev

If the Gentoo ebuild repository is synchronized using Git, or another method where Manifest files do not include ebuild checksums, Portage must be informed of this to prevent "masked by: corruption" errors:

root #echo 'thin-manifests = true' >> /var/db/repos/portage-crossdev/metadata/layout.conf

Instruct Portage and crossdev to use this ebuild repository:

FILE /etc/portage/repos.conf/crossdev.conf
location = /var/db/repos/portage-crossdev
priority = 10
masters = gentoo
auto-sync = no

Build and install the toolchain

Select an appropriate toolchain for the targeted architecture (the board in use); Most Arduino users will only want the AVR toolchain.

AVR (Arduino/Genuino/ATmicro/ATmega/etc.)

Build and install the AVR toolchain with this command:

root #crossdev -s4 --stable --portage --verbose --target avr
ARM (STM32/GD32/etc.)

Build and install the ARM toolchain with this command:

root #crossdev -s4 --stable --portage --verbose --target arm

If issues are encountered when crossdev is compiling the gcc stages, try:

root #USE="-openmp -hardened -sanitize -vtv" crossdev -s4 --stable --portage --verbose --target avr

Discouraged: Install non-Gentoo toolchain

The vendor-provided Atmel AVR toolchain is available for use, however it is untested.

An (old) article describing the use of the precompiled Debian toolchain is available here.

Installing the Arduino IDE

Official sources

An up-to-date version of the Arduino IDE is available in the official Gentoo repoisitory:

root #emerge --ask dev-embedded/arduino

Official download

  • Benefit: Always up to date.
  • Drawback: Not packaged for Gentoo. All or nothing. Not built from source. Requires manual updates.

Official tarball downloads (including beta and hourly versions).

Configuring the Arduino IDE

The Arduino IDE will create a default sketch directory on first launch, located at ~/Arduino. This location can be changed within the Arduino IDE's preferences.

If targeting any platforms that aren't included in the default distribution (E.g. ATtiny processors, or ARM processors such as the STM32 or GD32) new Arduino platform implementations (also known as "cores") must be installed. Cores can then be associated with board definitions.

Some example cores:

Using Eclipse IDE

Within the Eclipse IDE there are two available plugins for Arduino development. Plugins can be installed via user-provided update sites: Add the required site to Eclipse via Menu/Help/Software-updates/Add-site.

Installation of the Eclipse IDE is out of scope for this article. Please see Eclipse for that topic.

Arduino Eclipse Extension

The Arduino Eclipse Extension is a free Eclipse IDE plugin for Arduino projects developed by Jantje. It depends on the installation of Arduino IDE.

Use the update site "" for the installation of a plugin version which is compatible with Arduino 1.0.4 and Eclipse Helios and Indigo.

Use the update site "" for installation of a plugin version which is compatible with Arduino 1.5.x and Eclipse Juno.

AVR Eclipse Plugin

The AVR Eclipse Plugin is a free Eclipse IDE plugin used to develop for boards with AVR Atmel microprocessors. The plugin is not designed for Arduino boards, but can used with them and It is not necessary to install the Arduino IDE to use this plugin. More information can be found on the official wiki.

Use the update site "" to install the plugin.

The Arduino Eclipse Extension V1 contains the AVR Eclipse Plugin as such it is not possible to have both installed simultaneously.
The Arduino Eclipse Extension V2 does not contain the plugin, so the AVR Eclipse Plugin may be installed alongside the Arduino Eclipse Extension.

Tips and Tricks

udev rules

A udev rule can be used to create symlinks such as /dev/arduino when the board is connected. This is particularly useful in cases where more than one Arduino board will be connected simultaneously.

Arduino NG

Create the file /etc/udev/rules.d/12-mikrocontroller.rules and add following line to the file:

FILE /etc/udev/rules.d/12-mikrocontroller.rules
SUBSYSTEMS=="usb", ATTRS{product}=="FT232R USB UART", ATTRS{manufacturer}=="FTDI", NAME="ttyUSB%n", SYMLINK+="arduino"

Arduino MEGA

Create the file /etc/udev/rules.d/12-mikrocontroller.rules and add following line to the file:

FILE /etc/udev/rules.d/12-mikrocontroller.rules
SUBSYSTEMS=="usb", ATTRS{product}=="Arduino Mega 2560", ATTRS{manufacturer}=="Arduino (", NAME="ttyACM%n", SYMLINK+="arduino"


Deprecated items in avr-libc v1.8.0 and above (and Mega 2560)

If the following message is received, a known compatibility issue has been encountered.

CODE Errors during compilation
/usr/share/arduino/hardware/arduino/cores/arduino/HardwareSerial.cpp:107:41: error: attempt to use poisoned "SIG_USART0_RECV"
/usr/share/arduino/hardware/arduino/cores/arduino/HardwareSerial.cpp:117:15: error: attempt to use poisoned "SIG_USART0_RECV"
/usr/share/arduino/hardware/arduino/cores/arduino/HardwareSerial.cpp:161:15: error: attempt to use poisoned "SIG_USART0_RECV"
/usr/share/arduino/hardware/arduino/cores/arduino/HardwareSerial.cpp:178:15: error: attempt to use poisoned "SIG_USART0_RECV"
/usr/share/arduino/hardware/arduino/cores/arduino/HardwareSerial.cpp:195:15: error: attempt to use poisoned "SIG_USART0_RECV"

To resolve this issue modify Arduino.h to the following:

FILE /usr/share/arduino/hardware/arduino/cores/arduino/Arduino.h
#ifndef Arduino_h
#define Arduino_h
//start: fix the compatibility issue
//end: fix the compatibility issue
#include <stdlib.h>

Insufficient permissions for /dev/ttyACM0

CODE Error when accessing serial port
can't open device "/dev/ttyACM0": Permission denied

Users attempting to access the serial port in question must be a part of the dialout group.

Add a user to the dialout group by issuing:

root #gpasswd -a larry dialout
Larry will need to log off and back on before permissions granted by the group will take effect, until then he will be unable to access the device

Missing arduino-builder

If the following error message is encountered, the arduino-builder binary is not in the location that the Arduino IDE expects.

CODE No such file or catalogue
Caused by: Cannot run program "/usr/share/arduino/arduino-builder": error=2, No such file or directory

Run the following command to symlink the existing arduino-builder binary:

root #ln -sf /usr/bin/arduino-builder /usr/share/arduino/arduino-builder

Gray window, Arduino IDE not resizing with WM, menus immediately closing

If encountering weird window behavior with the Arduino IDE on the window manager:


Arduino IDE fail to compile sketches due to missing --tools parameter

If the following message is received, a known bug has been encountered:

CODE Parameter 'tools' is mandatory
Parameter 'tools' is mandatory
Usage of /usr/share/arduino/arduino-builder:
  -build-cache string
      builds of 'core.a' are saved into this folder to be cached and reused
  -build-options-file string
Error compiling for board Arduino Uno.

Create the /usr/share/arduino/tools-builder directory to fix it:

root #mkdir /usr/share/arduino/tools-builder

See also

  • Embedded Handbook — a collection of community maintained documents providing a consolidation of embedded and SoC knowledge for Gentoo.

External resources