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:

```bash
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:

```bash
./setup.sh --help
```

Useful options:

```bash
# 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

```text
.
├── 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:

```text
studuino:avr:studuino
```

The project defaults are in `sketch.yaml`:

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

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

```text
/dev/ttyACM0
/dev/ttyUSB1
```

Check connected boards with:

```bash
arduino-cli board list
```

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

```bash
arduino-cli board listall | grep -i studuino
```

Expected output includes:

```text
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:

```bash
arduino-cli compile
```

Compile with an explicit target:

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

Upload using the port from `sketch.yaml`:

```bash
arduino-cli upload
```

Upload with an explicit port:

```bash
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:

```bash
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:

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

Or generate it directly:

```bash
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:

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

vim.lsp.enable("clangd")
```

For older `nvim-lspconfig` versions, use:

```lua
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:

```text
Resources/nvim/lua/plugins/arduino.lua
```

Copy it into your Neovim configuration if needed:

```bash
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:

```text
.arduino_config.lua
```

The repository already contains this file:

```lua
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:

```bash
./setup.sh --with-monitor
```

Open the monitor at the configured baud rate:

```bash
picocom /dev/ttyUSB0 --baud 115200
```

Exit `picocom` with:

```text
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:

```text
~/Arduino/hardware/studuino/studuino/avr
```

the hardware directory has an extra `studuino` component. Run:

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

The supported path is:

```text
~/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:

```bash
arduino-cli lib install Servo
```

Or rerun:

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

### Permission denied for `/dev/ttyUSB0`

Check the current groups:

```bash
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:

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

### No board is detected

Try:

```bash
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:

```yaml
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:

```bash
./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.