Przejdź do treści
Biblioteka skilli
Inne · Automatyzacja

qoduck-setup

/qoduck-setup

Uruchamia urządzenie głosowe Qoduck: wgrywa firmware, łączy z Wi-Fi, tworzy token agenta i sprawdza pętlę głosową.

Repozytorium
esp32-qoduck ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
01.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
9
Przestarzałość

Brak sygnałów. Repozytorium zmienione 01.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Uruchamia urządzenie głosowe Qoduck: wgrywa firmware, łączy z Wi-Fi, tworzy token agenta i sprawdza pętlę głosową.

Oryginalny opis (EN)

Bring a Qoduck voice gadget online: flash the firmware, put it on Wi-Fi, create a Qoder Cloud Agents token plus conversation, and verify the voice loop. Use for first-time setup, re-provisioning a device after a reset, or when the device says it cannot reach Qoder.

Jak działa

  1. 1. Prerequisites
  2. 2. Flash the firmware
  3. 3. Create the Qoder token and conversation
  4. 4. Put the device on Wi-Fi
  5. 5. Verify
  6. 6. Controls
  7. 7. Memory and new sessions
  8. Troubleshooting
  9. Cost
  10. 中文速记
Sekcje z nagłówków SKILL.md, w oryginale · 181 linii, 1 359 słów
Podgląd SKILL.md
---
name: qoduck-setup
description: >-
  Bring a Qoduck voice gadget online: flash the firmware, put it on Wi-Fi, create a Qoder
  Cloud Agents token plus conversation, and verify the voice loop. Use for first-time setup,
  re-provisioning a device after a reset, or when the device says it cannot reach Qoder.
---

# Qoduck setup

Everything below is host-side work. The device itself has no config UI beyond its scroll-wheel
menu, so the order is: flash → Wi-Fi → Qoder credentials → verify.

## 1. Prerequisites

- ESP-IDF **v6.0.1** (`~/esp/esp-idf-v6`, `./install.sh esp32s3`, `. ./export.sh`)
- Node.js 20+ (only for `esp32/tools/qca/provision.mjs`)
- A Qoder account — https://qoder.com (international) or https://qoder.cn (China)
- Chrome on a desktop or Android phone (Web Bluetooth is not available in Safari)

Credentials are **never** committed. They live in NVS on the device, in
`esp32/components/qca_voice/qca_config.local.h` (git-ignored) or in a `-DQCA_TOKEN=` build flag.

## 2. Flash the firmware

```sh
cd esp32
idf.py -B build-muse-sensecap-watcher -DIDF_TARGET=esp32s3 \
  -DSDKCONFIG=build-muse-sensecap-watcher/sdkconfig \
  -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;devices/sdkconfig.muse;devices/sdkconfig.muse-sensecap-watcher" \
  build
idf.py -B build-muse-sensecap-watcher -p /dev/tty.usbmodemXXXX flash monitor
```

First boot: the screen shows the boot animation, then a duck face, and the serial log shows
`hb t=...s setup=advertising wifi=down ws=down ble=advertising`. No Wi-Fi yet — that is expected.

## 3. Create the Qoder token and conversation

**Token.** Sign in to Qoder, open <https://qoder.com/cloud/pat-keys> (China site:
<https://qoder.com.cn/cloud/pat-keys>), and create a Personal Access Token (`pt-...`). Treat it like
a password: it bills to your account. Tokens are host-specific — one minted on `.com` will not
authenticate against the `.cn` endpoint.

**Conversation.** A device talks to one Qoder Cloud Agents *realtime conversation*. Create it once:

```sh
cd esp32/tools/qca
QODER_ACCESS_TOKEN=pt-... node provision.mjs
```

It creates (or reuses) a voice template with a spoken-answer system prompt and web tools, an
identity, and a conversation, then writes `qca-conversation.json` and prints the three values you
need. Creating a conversation costs credits (242 at the time of writing; reconnecting to an
existing one is much cheaper), so keep that file.

## 4. Put the device on Wi-Fi

### Option A — BLE web page (no cable, recommended)

```sh
esp32/tools/serve_setup.sh          # serves ble_setup.html on :8765
```

1. Open the printed URL in Chrome (`http://127.0.0.1:8765` on the desktop, or the LAN address on a
   phone).
2. *Connect device* → pick `Qoduck-xxxx` in the chooser. The page filters by **name prefix**
   because the setup characteristics are not in the BLE advertisement; if the list is empty, use
   *Show all devices*.
3. Fill SSID / password → *Send to device*. Then paste the Qoder token (values over ~180 bytes are
   chunked automatically) and the conversation id.

The phone/desktop needs a secure origin for Web Bluetooth. Over plain `http://` add the URL to
`chrome://flags/#unsafely-treat-insecure-origin-as-secure` and relaunch Chrome.

### Option B — on the device

Swipe to *Settings → WIRELESS NETWORK* for SSID/password, and *Settings → QODER* for the API URL
(`wss://api.qoder.com/api/v1/forward/realtime`), conversation id and token. This is also how you
rotate a token without reflashing.

### Option C — build time

```c
// esp32/components/qca_voice/qca_config.local.h  (git-ignored)
#define QCA_TOKEN  "pt-..."
#define QCA_WS_URL "wss://api.qoder.com/api/v1/forward/realtime?conversation_id=conv_..."
```

## 5. Verify

Serial log after the device joins Wi-Fi:

```
wifi=up ws=up          # connected to Qoder
hb t=42s setup=done wifi=up ws=up ble=advertising
```

On screen, *Settings → QODER* shows 已连接 / 未连接 / 未配置. Then just talk — the duck sways while
audio streams back. Expect 1.0–2.5 s to the first spoken frame.

## 6. Controls

| Gesture | Action |
|---|---|
| speak | conversation (always-listening) |
| tap wheel | pet the duck — hops once, hearts float up |
| double-tap wheel | dizzy — spins, star orbit, X eyes |
| turn wheel | look around |
| hold 1.2 s | dozing off (closed eyes, Zzz) |
| hold 2.4 s | asleep (screen off) |
| hold 4.2 s | power off, after the goodbye animation |
| double-turn wheel | toggle BLE phone pairing |
| swipe left / right | switch screens (status, menu) |
| wheel click in menu | open / select item |
| menu item 新会话 | start a new conversation, memory kept |

The wheel emotes are cosmetic only — they never touch the audio path, so it is safe to play with
them while a conversation is open. `qca> emote pet|dizzy|look|sleepy` replays one from the serial
console.

### Shutdown animation, and how to see it without powering off

Powering off plays a 1.5 s goodbye on the avatar (blink, sink, then the pixels dissolve with an
ordered dither) while the backlight fades on the same clock; the rail is cut 0.2 s after it finishes.
Two serial console commands help when you cannot watch the screen:

| Command | What it does |
|---|---|
| `bye` | plays the goodbye animation and dumps the 64×64 avatar grid as ASCII (`@dump k=… cut=… lit=…/4096` plus a 32×32 picture: `#` full, `+` partly dithered out, `.` dark). Does not power off. |
| `off` | the real thing — animation, then power off. |
| `emote pet\|dizzy\|look\|sleepy` | replays one wheel emote and dumps ASCII frames at 4 points (`active=` is the emote id, 0 once it has ended). |

`k` is the animation clock (0 → 1), `cut` the dither threshold; `lit` reaching 0 is what "fully
dissolved" looks like. Only the qca console sees these: muse's own console and the qca REPL share the
same UART and the REPL wins.

## 7. Memory and new sessions

A conversation id is a working context, not a memory. Memory lives in a Qoder **Memory Store** bound
to the `(identity, template)` pair, so it survives new conversations and reboots as long as you keep
using the same identity and template.

* **New conversation on the device**: *Settings → QODER → 开新会话*, the wheel menu item **新会话**,
or the serial console `new`. The firmware stops the WebSocket first (a TLS handshake for the REST call
needs ~20 KB of contiguous internal RAM, which is what is left while realtime is up), POSTs
`/api/v1/forward/realtime/conversations`, stores the new id in NVS, then reconnects.
* **Identity / template**: `ids` prints them, `ids idn_… tmpl_…` writes them to NVS. They are only
needed for *creating* conversations — an existing conversation id works without them.
* **Make sure memory can be written**: the template needs `Read` and `Write` in `enabled_tools`, and
the system prompt should ask it to record durable facts. `provision.mjs` does both. Verify with
`curl -H "Authorization: Bearer $QODER_PAT" https://api.qoder.com/api/v1/forward/templates/tmpl_…`.
* **Check the store**: `GET /api/v1/forward/identities/idn_…/templates/tmpl_…/memory_stores` lists it,
and `GET /api/v1/forward/memory_stores/memstore_…` shows `entry_count` / `total_size` / `updated_at`
so you can see it grow. The read-a-single-entry endpoint is not documented publicly; ask the agent
"你还记得我叫什么吗" instead. A conversation that just ended may still be queued for
consolidation, so recent facts can take a minute to appear.

## Troubleshooting

| Symptom | Cause / fix |
|---|---|
| BLE chooser is empty | page filters by name prefix; the setup service UUID is not advertised. Use *Show all devices*, or check `CONFIG_HOMEHUB_BLE_NAME_PREFIX` |
| `跳过连接:Qoder 地址或 token 为空` | no token or URL: fill Settings → QODER |
| `ws=down` forever | wrong conversation id, expired PAT, or the device cannot reach `api.qoder.com` on 443 (check captive portal / proxy) |
| Token rejected | PATs are host-specific: a token minted for `api.qoder.com` does not work against the `.cn` endpoint |
| Audio but no reply | server-side VAD never fired: raise mic gain (*Settings → MIC GAIN*) or speak closer |
| Reply cut off | screen sleep is fine, but Wi-Fi power save can drop frames: keep the device on 5 V USB |
| `开新会话` fails, `开新会话缺配置` | identity/template missing: run `ids idn_… tmpl_…` over the console |
| `开新会话失败 … HTTP 4xx` | PAT expired, or the identity/template pair does not belong to it |
| It forgot everything | memory needs the template's `Read`/`Write` tools; also confirm both sessions used the same identity *and* template |

## Cost

Hardware only: SenseCAP Watcher ≈ **$54.90–$62.34**. Everything in this repository is free to build
and flash. The voice service is metered by Qoder on your own account — check the dashboard after the
first session instead of trusting an estimate.

## 中文速记

1. 刷固件:`idf.py -B build-muse-sensecap-watcher ... build / flash`。
2. 建 token:打开 <https://qoder.com/cloud/pat-keys>(国内站 <https://qoder.com.cn/cloud/pat-keys>),新建 PAT(`pt-...`)。
3. 建会话:`QODER_ACCESS_TOKEN=pt-... node esp32/tools/qca/provision.mjs`,记下 conversation id。
4. 配网:`esp32/tools/serve_setup.sh` 起页面 → 手机 Chrome 连 `Qoduck-xxxx` → 填 SSID/密码/Token。
5. 验证:串口看 `wifi=up ws=up`,设置页显示“已连接”,直接说话即可。
6. 换会话:设置 → QODER → 开新会话,或菜单「新会话」,或串口 `new`;记忆不会丢(挂在身份+模板上)。
7. 花费:只有硬件钱,Watcher 约 $55–62;语音服务按 Qoder 账户实际用量计费,看后台。

Wersje

W bazie nie ma innych skilli o nazwie qoduck-setup.

Migawka bazy z 13.11.2026 · wersja paczki e77ef55be2be (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100code-mate-qoder
    Uruchamia Qoder CLI nieinteraktywnie ze strukturalnym wynikiem, gdy użytkownik chce przekazać zadanie programistyczne do Qodera.
  • 98ruview-hardware-setup
    Buduje, wgrywa i konfiguruje firmware ESP32-S3 i ESP32-C6 dla węzłów czujników CSI, także przez WiFi, i odczytuje logi szeregowe.
  • 98ruview-hardware-setup
    Buduje, wgrywa i konfiguruje firmware ESP32-S3 i ESP32-C6 dla węzłów czujników CSI, także przez WiFi, i odczytuje logi szeregowe.
  • 98qoder-daily-claim
    Automatycznie odbiera codzienne kredyty Qoder CN z lokalnego logowania i może działać jako zadanie harmonogramu w Windows.
  • 85m5-onboard
    Wykrywa podłączone urządzenie M5Stack ESP32, wgrywa firmware UIFlow 2.0 i instaluje aplikację MicroPython, by urządzenie uruchamiało się bez ekranu parowania.
  • 100bk3266
    Czyta, zapisuje i zmienia firmware układów BK3266 w słuchawkach przez UART, np. komunikaty głosowe i ustawienia.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.