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.

## 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:

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

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

Useful options:

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

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

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

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

```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. It is checked into this repository and is installed by the setup script. If it is missing, 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 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:

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