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 eval still 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)