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, clangd, and Neovim.

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 legacy Studuino hardware platform.
• Arduino CLI project defaults for studuino:avr:studuino.
• Installation of the required Servo library.
• Optional cleanup of unrelated user libraries.
• A generated compile_commands.json for clangd and Neovim.
• Optional picocom serial-monitor support.
• A LazyVim/Arduino-Nvim configuration template.

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 these Arch packages by default:

• arduino-cli
• clangd
• make
• neovim
• python
• unzip

It can optionally install picocom with --with-monitor.

Quick start

From the repository root:

cd /path/to/this/repository
./setup.sh

The script performs the following tasks:

1. Installs required Arch packages.
2. Adds the current user to uucp and dialout.
3. Initializes the Arduino CLI configuration if necessary.
4. Installs the AVR core when it is missing.
5. Installs the Studuino hardware definition.
6. Installs the libraries from Resources/studuino_v1_lib.zip.
7. Installs Servo, which is required by Studuino.h.
8. Ensures the sketch and default FQBN are configured.
9. Generates compile_commands.json for clangd.
10. Verifies board discovery and compilation.

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 picocom for a serial monitor
./setup.sh --with-monitor

# Remove user libraries not supplied by the Studuino bundle
./setup.sh --clean

# Replace existing Studuino library and hardware files
./setup.sh --force

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

--clean is destructive. It preserves the libraries supplied in the Studuino ZIP and Servo, but removes other directories under the configured Arduino libraries directory. Back up any libraries you want to keep.

--force overwrites existing Studuino library and hardware files. Use it only 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       # clangd compilation database
├── 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.

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. The Studuino target is an ATmega168 target, so the available program storage is smaller than a default Arduino Uno/ATmega328 build.

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

The setup script installs clangd and generates compile_commands.json in the project root. clangd automatically searches the project directory for this file.

The initial database is generated from the minimal sketch, so it may not contain the Studuino library include paths. If clangd reports Studuino.h file not found after adding #include <Studuino.h>, refresh the database with the setup script after changing the sketch.

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, but Servo is distributed separately from the Studuino ZIP. 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 skips existing packages, libraries, and core installations unless --force is supplied. It always verifies the final board, libraries, and project compilation.

To inspect all available options:

./setup.sh --help

License and source materials

The Studuino hardware archive and Studuino library archive are kept in Resources/ because they use a legacy/manual Arduino hardware layout. Keep the archives with the project so the setup can be recreated on another Linux machine.