Add Studuino Linux Neovim setup
This commit is contained in:
@@ -0,0 +1,413 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user