429 lines
11 KiB
Markdown
429 lines
11 KiB
Markdown
# 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:
|
|
|
|
```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.
|