gpio-llm-pico-rpi5
A 2.74M-parameter Llama-style model, trained from scratch, that turns one English request for a Raspberry Pi 5 GPIO header into one JSON action:
User: turn on the LED on GPIO 17
Assistant: {"action":"gpio_write","pin":17,"value":"HIGH"}
This is the smallest of the three sizes: the fastest and the least accurate. It is part of GPIO-LLM: the code, the C inference engine and the training scripts are on GitHub, and the data is AwaleSagar/gpio-llm-rpi5-actions. The other sizes are gpio-llm-nano-rpi5, gpio-llm-base-rpi5.
⚠️ The model is not a safety layer. It picks an action; a deterministic validator must check every action against the board's rules before anything touches a pin. Before the validator, 3.51% of the refusal or clarification cases in
evalstill come out as an executable action.
Use it
On a Raspberry Pi, with the C engine (no Python, no ML framework; int8 weights):
git clone https://github.com/AwaleSagar/gpio-llm && make -C gpio-llm/engine
cd gpio-llm/engine
for f in pico.gllm gpio_llm_bpe_12k.gltk grammar_v2.txt; do
curl -LO https://huggingface.co/AwaleSagar/gpio-llm-pico-rpi5/resolve/main/$f
done
build/gpiollm -m pico.gllm -t gpio_llm_bpe_12k.gltk -g grammar_v2.txt "turn on the LED on GPIO 17"
build/gpiollm -m pico.gllm -t gpio_llm_bpe_12k.gltk -g grammar_v2.txt \
--context '{"device_mappings":{"fan":23}}' "switch the fan off"
The engine decodes under a grammar built from the training labels, so its output is always one of the JSON shapes the dataset uses.
With transformers (fp32, unconstrained greedy decoding):
from transformers import AutoModelForCausalLM, AutoTokenizer
repo = "AwaleSagar/gpio-llm-pico-rpi5"
tok = AutoTokenizer.from_pretrained(repo)
model = AutoModelForCausalLM.from_pretrained(repo)
prompt = "User: turn on the LED on GPIO 17\nAssistant:"
ids = tok(prompt, return_tensors="pt").input_ids
out = model.generate(ids, max_new_tokens=200, do_sample=False)
print(tok.decode(out[0, ids.shape[1]:], skip_special_tokens=True).strip())
Prompt format. User: <request>\nAssistant:, optionally preceded by one context line such as
Context: {"device_mappings":{"red_led":16}}\n or Context: {"available_pins":[16,17,18,25]}\n. The answer
starts with a space and ends with <|endoftext|>. Multi-turn clarification follows the dataset format
(...\nAssistant: <question>\nUser: <answer>\nAssistant:).
Model
| Architecture | LlamaForCausalLM: 6 layers, d_model 128, 4 heads (head_dim 32), SwiGLU FFN 352, RoPE θ = 10000, RMSNorm ε = 1e-05, tied embeddings |
| Parameters | 2,741,888 |
| Vocabulary / context | 12,000 (byte-level BPE gpio_llm_bpe_12k, from the dataset repo) / 256 tokens |
| Weights | model.safetensors (fp32); pico.gllm: int8 Q8_0, groups of 32, for the C engine |
Training
Both stages ran on one rented RTX 4090 (24 GB), PyTorch 2.11 + CUDA 12.8, transformers 5.17.
| Stage | Data | Steps × batch | LR | Result | Time |
|---|---|---|---|---|---|
| Pretraining | 550M tokens of fineweb-edu-dedup (SmolLM corpus), 1 epoch | 8,392 × 65,536 tokens | 0.003, cosine, bf16 | val loss 3.8392 (perplexity 46.5) on 0.5M held-out tokens | 9.6 min |
| SFT | all 1,678,821 v2 train rows, 2 epochs; loss on the answer tokens only; 4×256 English tokens replayed every 12 steps (~1.1% of loss tokens) | 13,116 × 256 rows | 0.002, cosine | eval_core answer-token loss 0.0216 | 8.5 min |
The pretraining learning rate came from a sweep on the nano shape at 55M tokens (lr → val loss): 0.001 → 4.5915, 0.002 → 4.2903, 0.003 → 4.1836, 0.005 → 4.1985.
Logs are in training/.
Evaluation
Exact match compares canonical JSON (same object, key order ignored) with the label. eval has 26,297 rows from
132 phrasing templates that never appear in training; eval_core is a 5,083-row stratified subset.
| Setup | Split | Exact match | Valid JSON | Unsafe execute* |
|---|---|---|---|---|
| PyTorch fp32, greedy | eval | 91.88% | 99.96% | 3.51% |
| PyTorch fp32, greedy | eval_core | 90.64% | 99.96% | 3.52% |
| C engine int8, no grammar | eval_core | 90.67% | 99.94% | 3.41% |
| C engine int8, grammar | eval_core | 90.69% | 100.00% | 3.41% |
* Share of the refusal/clarification rows (1,845 in eval_core) where the model produced an executable action instead. This is measured before any validator.
Latency with the C engine and the grammar, on all 5,083 eval_core requests from raw text (tokenizer included), 4 threads:
| Device | p50 | p95 |
|---|---|---|
| Raspberry Pi Zero 2 W, 64-bit Raspberry Pi OS, no heatsink (throttled at ~81 °C) | 86 ms | 186 ms |
| Apple M5 laptop | 1.5 ms | 2.8 ms |
The Pi's outputs were byte-identical to the Mac's on all 5,083 rows. The int8 engine's greedy answers matched fp32 PyTorch on 199/200 sampled rows (minimum next-token logit cosine 0.99978).
Limitations
- Pi 5 labels only. The v2 data has no board field, so the labels follow the Pi 5 (RP1) rules, e.g. per-pin drive strength. On older boards, board-specific cases must be caught by the validator.
- Synthetic English requests. They come from templates, a rule-based generator and (v1) model rewrites. Real users will phrase things in ways the model has not seen.
- Scope. Digital I/O, PWM, pulses, waits, sequences, errors and clarifications only. There are no bus transactions (I2C/SPI/UART data), and the context is 256 tokens.
Files
| File | What it is |
|---|---|
model.safetensors, config.json, generation_config.json | fp32 transformers checkpoint |
tokenizer.json, tokenizer_config.json | the dataset's gpio_llm_bpe_12k tokenizer |
pico.gllm | int8 weights for the C engine |
gpio_llm_bpe_12k.gltk, grammar_v2.txt | tokenizer and output grammar for the C engine |
training/ | training logs, LR sweep, eval summaries (JSON) |
Licence and attribution
The weights are released under CC-BY-4.0; the code on GitHub is Apache-2.0. The training data carries its own terms:
- the fine-tuning data, AwaleSagar/gpio-llm-rpi5-actions, is CC-BY-4.0
- its knowledge-base scenes are CC BY-SA 4.0
- the user wording in its v1
teacher_*rows was generated with third-party models, so check those providers' terms on using model outputs - the pretraining text is fineweb-edu-dedup (ODC-By 1.0)