# KylinBot on Nucleo-F401RE — Step-by-Step Guide

Run KylinBot on your Mac or Linux host. Connect a Nucleo-F401RE via USB. Control GPIO (LED, pins) via Telegram or CLI.

---

## Get Board Info via Telegram (No Firmware Needed)

KylinBot can read chip info from the Nucleo over USB **without flashing any firmware**. Message your Telegram bot:

- *"What board info do I have?"*
- *"Board info"*
- *"What hardware is connected?"*
- *"Chip info"*

The agent uses the `hardware_board_info` tool to return chip name, architecture, and memory map. With the `probe` feature, it reads live data via USB/SWD; otherwise it returns static datasheet info.

**Config:** Run `kylinbot onboard` (hardware step adds the board interactively), or use `kylinbot config set peripherals.boards.0.board nucleo-f401re`, `transport serial`, and `path <your-serial-port>`. See the [Config reference](../reference/config.md) for all fields.

**CLI alternative:**

```bash
cargo build --features hardware,probe
kylinbot hardware info
kylinbot hardware discover
```

---

## What's Included (No Code Changes Needed)

KylinBot includes everything for Nucleo-F401RE:

| Component | Location | Purpose |
|-----------|----------|---------|
| Firmware | `firmware/nucleo/` | Embassy Rust — USART2 (115200), gpio_read, gpio_write |
| Serial peripheral | `crates/kylinbot-hardware/src/peripherals/serial.rs` | JSON-over-serial protocol (same as Arduino/ESP32) |
| Flash command | `kylinbot peripheral flash-nucleo` | Builds firmware, flashes via probe-rs |

Protocol: newline-delimited JSON. Request: `{"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}}`. Response: `{"id":"1","ok":true,"result":"done"}`.

---

## Prerequisites

- Nucleo-F401RE board
- USB cable (USB-A to Mini-USB; Nucleo has built-in ST-Link)
- For flashing: `cargo install probe-rs-tools --locked` (or use the [install script](https://probe.rs/docs/getting-started/installation/))

---

## Phase 1: Flash Firmware

### 1.1 Connect Nucleo

1. Connect Nucleo to your Mac/Linux via USB.
2. The board appears as a USB device (ST-Link). No separate driver needed on modern systems.

### 1.2 Flash via KylinBot

From the kylinbot repo root:

```bash
kylinbot peripheral flash-nucleo
```

This builds `firmware/nucleo` and runs `probe-rs run --chip STM32F401RETx`. The firmware runs immediately after flashing.

### 1.3 Manual Flash (Alternative)

```bash
cd firmware/nucleo
cargo build --release --target thumbv7em-none-eabihf
probe-rs run --chip STM32F401RETx target/thumbv7em-none-eabihf/release/nucleo
```

---

## Phase 2: Find Serial Port

- **macOS:** `/dev/cu.usbmodem*` or `/dev/tty.usbmodem*` (e.g. `/dev/cu.usbmodem101`)
- **Linux:** `/dev/ttyACM0` (or check `dmesg` after plugging in)

USART2 (PA2/PA3) is bridged to the ST-Link's virtual COM port, so the host sees one serial device.

---

## Phase 3: Configure KylinBot

Enable `[peripherals]` and add a `[[peripherals.boards]]` entry for the Nucleo (`board = "nucleo-f401re"`, `transport = "serial"`, `path = "/dev/cu.usbmodem101"` — adjust to your serial port). See the [Config reference](../reference/config.md) for all fields.

---

## Phase 4: Run and Test

```bash
kylinbot daemon --host 127.0.0.1 --port 42617
```

Or use the agent directly:

```bash
kylinbot agent --message "Turn on the LED on pin 13"
```

Pin 13 = PA5 = User LED (LD2) on Nucleo-F401RE.

---

## Summary: Commands

| Step | Command |
|------|---------|
| 1 | Connect Nucleo via USB |
| 2 | `cargo install probe-rs-tools --locked` |
| 3 | `kylinbot peripheral flash-nucleo` |
| 4 | `kylinbot onboard` → hardware step (or `kylinbot config set peripherals.boards.0.path <serial-port>`) |
| 5 | `kylinbot daemon` or `kylinbot agent -m "Turn on LED"` |

---

## Troubleshooting

- **flash-nucleo unrecognized** — Build from repo: `cargo run --features hardware -- peripheral flash-nucleo`. The subcommand is only in the repo build, not in crates.io installs.
- **probe-rs not found** — `cargo install probe-rs-tools --locked` (the `probe-rs` crate is a library; the CLI is in `probe-rs-tools`)
- **No probe detected** — Ensure Nucleo is connected. Try another USB cable/port.
- **Serial port not found** — On Linux, add user to `dialout`: `sudo usermod -a -G dialout $USER`, then log out/in.
- **GPIO commands ignored** — Check `path` in config matches your serial port. Run `kylinbot peripheral list` to verify.
