gpio-llm-base-rpi5

gpio-llm-base-rpi5

A 18.77M-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 largest and most accurate of the three sizes. 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-pico-rpi5, gpio-llm-nano-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, 0.96% 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 base.gllm gpio_llm_bpe_12k.gltk grammar_v2.txt; do
  curl -LO https://huggingface.co/AwaleSagar/gpio-llm-base-rpi5/resolve/main/$f
done
build/gpiollm -m base.gllm -t gpio_llm_bpe_12k.gltk -g grammar_v2.txt "turn on the LED on GPIO 17"
build/gpiollm -m base.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-base-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

Training

Both stages ran on one rented RTX 4090 (24 GB), PyTorch 2.11 + CUDA 12.8, transformers 5.17.

The pretraining learning rate came from a sweep on the base shape at 55M tokens (lr → val loss): 0.0005 → 4.5519, 0.001 → 4.2294, 0.002 → 4.0577. 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.

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

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 200/200 sampled rows (minimum next-token logit cosine 0.99759).

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

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)