Studuino/README.md

Studuino on Linux with Neovim

A development template for using the Artec Studuino (ATmega168/328, 3.3 V, 8 MHz) on Arch Linux with arduino-cli and optional clangd/Neovim tooling.

This repository contains the Studuino hardware definition, the legacy Studuino libraries, an Arduino CLI setup script, and optional Neovim integration resources.

Features

• Manual installation of the checked-in legacy Studuino hardware platform.
• Arduino CLI project defaults for studuino:avr:studuino.
• Installation of the checked-in Studuino libraries, including Servo.
• Optional cleanup of unrelated user libraries.
• A generated, git-ignored compile_commands.json for clangd and Neovim.
• A real Studuino Blink smoke-test build during setup.
• Optional Neovim/Arduino language-server tooling.
• Optional picocom serial-monitor support.
• A LazyVim/Arduino-Nvim configuration template.

Libraries

Custom or adapted libraries are located in the /libraries/ directory. These include:

• ColorSensor
• MPU6050
• BusIOForStuduino
• Clock
• Servo
• Adafruit_CircuitPlayground
• IRremoteForStuduino

When creating new programs, ensure the header files for the components you are using are properly included in your sketches. Use the provided studuino_boilerplate snippet to get started quickly.

Requirements

• Arch Linux or another Linux distribution with bash.
• An Artec Studuino board connected over USB.
• A user account with permission to use serial devices.
• Internet access for the initial Arduino CLI core/library installation.

The setup script installs arduino-cli by default. On Arch Linux, it can also install editor tooling with --with-editor:

• clang (provides clangd)
• neovim
• arduino-language-server

It can optionally install picocom with --with-monitor. On other distributions, use --skip-packages and install the required commands through the distribution's package manager.

Quick start

From the repository root:

cd /path/to/this/repository
./setup.sh --with-editor

The script performs the following tasks:

1. Installs the required packages for the selected options.
2. Adds the current user to uucp and dialout.
3. Initializes the Arduino CLI configuration if necessary.
4. Installs or upgrades the Arduino AVR core to a supported version.
5. Installs the checked-in Studuino hardware definition.
6. Installs the checked-in Studuino libraries, including Servo.
7. Ensures the sketch and default FQBN are configured.
8. Generates compile_commands.json for clangd.
9. Compiles the bundled Studuino Blink smoke test.
10. Compiles the project and verifies board/library discovery.

Log out and back in after the first run if the script adds you to a new serial-port group. Group changes do not affect the current login session immediately.

Setup options

Show all options:

./setup.sh --help

Useful options:

# Do not install Arch packages or modify group membership
./setup.sh --skip-packages --skip-permissions

# Install Neovim, clangd, and Arduino language-server tooling
./setup.sh --with-editor

# Install picocom for a serial monitor
./setup.sh --with-monitor

# Remove user libraries not present in this repository
./setup.sh --clean

# Replace existing hardware/libraries with the checked-in versions
./setup.sh --force

# Skip regeneration of compile_commands.json
./setup.sh --skip-compile-db

--clean is destructive. It preserves the libraries checked into this repository, including Servo, but removes other directories under the configured Arduino libraries directory. Back up any libraries you want to keep.

--force overwrites existing Studuino hardware and library files with the checked-in versions. Use it after updating this repository or when intentionally refreshing the Studuino installation.

Project layout

.
├── Arduino.ino                 # Main sketch
├── sketch.yaml                 # arduino-cli project defaults
├── .arduino_config.lua         # Arduino-Nvim board/port configuration
├── setup.sh                    # Idempotent setup script
├── compile_commands.json       # Generated locally; not tracked
├── hardware/
│   └── studuino/
│       └── avr/
│           ├── boards.txt
│           ├── platform.txt
│           └── platform.local.txt
├── libraries/                  # Arduino user libraries
└── Resources/
    ├── arduino_IDE_hardware_settings_ver17x.zip
    ├── studuino_v1_lib.zip
    └── nvim/

The Studuino platform is manually installed because it predates the modern Boards Manager package format. The checked-in hardware/ and libraries/ trees are the canonical installation sources; the ZIP files under Resources/ are retained as upstream source material and provenance.

Board and port configuration

The default target is:

studuino:avr:studuino

The project defaults are in sketch.yaml:

default_fqbn: studuino:avr:studuino
default_port: /dev/ttyUSB0

Update default_port if the board appears at another device, such as:

/dev/ttyACM0
/dev/ttyUSB1

Check connected boards with:

arduino-cli board list

List all boards known to Arduino CLI, including the manually installed Studuino platform:

arduino-cli board listall | grep -i studuino

Expected output includes:

Studuino (3.3V, 8 MHz) w/ ATmega168    studuino:avr:studuino

If the port changes, update both sketch.yaml and .arduino_config.lua, or pass the port explicitly when uploading.

Compile and upload

Compile the current sketch using the project defaults:

arduino-cli compile

Compile with an explicit target:

arduino-cli compile --fqbn studuino:avr:studuino .

Upload using the port from sketch.yaml:

arduino-cli upload

Upload with an explicit port:

arduino-cli upload \
  --fqbn studuino:avr:studuino \
  --port /dev/ttyUSB0

The setup script verifies the project with a clean build and also compiles libraries/Studuino/example/Blink as a smoke test. The Studuino target is an ATmega168 target, so the available program storage is 14,336 bytes and static data is limited to 1,024 bytes.

Compile the bundled Blink example

The Studuino library includes a test example:

arduino-cli compile \
  --fqbn studuino:avr:studuino \
  libraries/Studuino/example/Blink

Neovim and clangd

With --with-editor, the setup script installs the clang package (which provides clangd), Neovim, and arduino-language-server. It generates compile_commands.json in the project root; the file is ignored by Git because its paths are specific to the local Arduino CLI installation.

The initial database is generated from Arduino.ino, which includes <Studuino.h> and <Clock.h>, so the complete bundled smoke-test dependency set is available to clangd. If you add a new library or change the FQBN, refresh the database with the setup script.

If you add a new library or change the FQBN, refresh the database with:

./setup.sh --skip-packages --skip-permissions

Or generate it directly:

build_dir="${XDG_CACHE_HOME:-$HOME/.cache}/arduino/studuino-compile-db"
mkdir -p "$build_dir"

arduino-cli compile \
  --clean \
  --fqbn studuino:avr:studuino \
  --only-compilation-database \
  --build-path "$build_dir" \
  .

cp "$build_dir/compile_commands.json" ./compile_commands.json

Minimal clangd configuration

For Neovim 0.11 or newer, add this to a Lua configuration or lazy.nvim plugin specification:

vim.lsp.config("clangd", {
  cmd = {
    "clangd",
    "--compile-commands-dir=" .. vim.fn.getcwd(),
  },
})

vim.lsp.enable("clangd")

For older nvim-lspconfig versions, use:

require("lspconfig").clangd.setup({
  cmd = {
    "clangd",
    "--compile-commands-dir=" .. vim.fn.getcwd(),
  },
})

Restart clangd after changing the board or library configuration if needed.

Arduino-Nvim integration

An optional LazyVim plugin specification is included at:

Resources/nvim/lua/plugins/arduino.lua

Copy it into your Neovim configuration if needed:

mkdir -p ~/.config/nvim/lua/plugins
cp Resources/nvim/lua/plugins/arduino.lua \
  ~/.config/nvim/lua/plugins/arduino.lua

The plugin file expects the board and port configuration in the project root:

.arduino_config.lua

The repository already contains this file:

return {
  board = "studuino:avr:studuino",
  port = "/dev/ttyUSB0",
  baudrate = "115200",
}

The included keymaps are:

Mapping	Action
<Leader>mc	Compile and verify
<Leader>mu	Upload
<Leader>ms	Show board, port, and FQBN status
<Leader>mg	Open the board/port GUI
<Leader>mm	Open the serial monitor
<Leader>ml	Open the library manager
<Leader>mb	Select a board
<Leader>mp	Select a port
<Leader>mr	Upload with manual reset

See Resources/nvim/README.md for the full Neovim resource notes.

Serial monitor

Install picocom through the setup script:

./setup.sh --with-monitor

Open the monitor at the configured baud rate:

picocom /dev/ttyUSB0 --baud 115200

Exit picocom with:

Ctrl-A, Ctrl-X

The monitor and upload commands cannot use the serial port simultaneously. Close the monitor before uploading.

Troubleshooting

invalid version directory

If Arduino CLI reports a path like:

~/Arduino/hardware/studuino/studuino/avr

the hardware directory has an extra studuino component. Run:

./setup.sh --skip-packages --skip-permissions

The supported path is:

~/Arduino/hardware/studuino/avr/boards.txt
~/Arduino/hardware/studuino/avr/platform.txt

Servo.h not found

Studuino.h includes the Servo library. It is checked into this repository and is installed by the setup script. If it is missing, install it with:

arduino-cli lib install Servo

Or rerun:

./setup.sh --skip-packages --skip-permissions

Permission denied for /dev/ttyUSB0

Check the current groups:

id -nG

The user should belong to uucp and/or dialout. If the setup script added the groups, log out and back in.

You can also check the device permissions with:

ls -l /dev/ttyUSB* /dev/ttyACM*

No board is detected

Try:

arduino-cli board list

If no board appears:

1. Check the USB cable and board power.
2. Check /dev/ttyUSB* or /dev/ttyACM*.
3. Verify serial-port group membership.
4. Try another USB port or cable.
5. Run arduino-cli board listall | grep -i studuino to confirm that the platform is installed.

The wrong board is used

Confirm that sketch.yaml contains:

default_fqbn: studuino:avr:studuino

The key must be default_fqbn; a top-level fqbn key is not used as the default by the installed Arduino CLI version.

Re-running setup

The setup script is designed to be rerun. It preserves existing user installations unless --force is supplied, verifies that the Arduino AVR core is at least version 1.8.8, and always verifies the board, libraries, Studuino smoke test, and project compilation.

To inspect all available options:

./setup.sh --help

License and source materials

The hardware and library ZIP files are retained in Resources/ as upstream source archives. The active, maintained definitions are the checked-in hardware/studuino/avr/ and libraries/ directories; the setup script installs from those directories.