# Tuyaos/wifi

> TuyaOS Wi-Fi via tal_wifi: station connect, AP start, scan, low power. WiFi、联网、STA、AP、扫网、配网、tal_wifi、连接路由器、热点。

- Skill: `tuya/tuyaos-wifi` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tuya/tuyaos-wifi`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tuya/tuyaos-wifi/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tuya (https://skillmd.com/u/tuya)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tuya/tuyaos-wifi

---


# TuyaOS Wi-Fi (`tal_wifi`)

**Demos:** `software/TuyaOS/apps/tuyaos_demo_examples/src/examples/os_wifi/`

| Mode | File | Entry |
|------|------|-------|
| Station (STA) | `example_os_wifi_sta.c` | `example_wifi_sta` |
| SoftAP | `example_os_wifi_ap.c` | `example_wifi_ap` |
| Scan | `example_os_wifi_scan.c` | `example_wifi_scan` |
| Low power | `example_os_wifi_low_power.c` | `example_wifi_low_power` |

Also related (product remote, not basic STA/AP):

| Topic | Demo |
|-------|------|
| Wi-Fi FFC master | `…/service_ffc_master/` (`tuya_iot_wifi_ffc_*`) |
| Wi-Fi FFC slaver | `…/service_ffc_slaver/` |

## Confirm first

- **Role:** STA / AP / scan / LP / FFC remote?
- **STA:** SSID + password (never hardcode secrets from demos — demos use placeholders).
- **AP:** SSID, password, channel, IP/mask/gw if static.
- Whether the app already runs a higher-level TuyaOS product init (`example_soc_*` / framework Wi-Fi). If the product stack owns Wi-Fi, do **not** double-`tal_wifi_init` without checking existing code.

## Core APIs

| Function | Role |
|----------|------|
| `tal_wifi_init(event_cb)` | register `WF_EVENT_E` callback, bring up stack |
| `tal_wifi_set_work_mode(mode)` | e.g. `WWM_STATION` / AP mode enum in headers |
| `tal_wifi_station_connect(ssid, passwd)` | STA join |
| `tal_wifi_get_ip(WF_STATION, &ip)` | read IP after `WFE_CONNECTED` |
| `tal_wifi_ap_start(...)` | softAP (see AP demo for exact args / `NW_IP_S`) |
| `tal_wifi_all_ap_scan` / `tal_wifi_release_ap` | scan + free results |
| `tal_wifi_lp_enable` / `tal_wifi_lp_disable` / `tal_wifi_set_lps_dtim` | low power |
| `tal_net_*` | UDP/TCP after link is up (AP demo uses broadcast) |

## STA pattern (adapt demo — do not leave xxxx credentials)

```c
#include "tuya_cloud_types.h"
#include "tal_log.h"
#include "tal_wifi.h"

static void wifi_event_callback(WF_EVENT_E event, void *arg)
{
    (void)arg;
    switch (event) {
    case WFE_CONNECTED: {
        NW_IP_S sta_info;
        memset(&sta_info, 0, sizeof(sta_info));
        if (tal_wifi_get_ip(WF_STATION, &sta_info) == OPRT_OK) {
            /* log ip/gw/mask — field names differ by SDK macro (nwipstr vs .ip) */
            TAL_PR_NOTICE("wifi connected");
        }
        break;
    }
    case WFE_CONNECT_FAILED:
        TAL_PR_ERR("wifi connect failed");
        break;
    case WFE_DISCONNECTED:
        TAL_PR_NOTICE("wifi disconnected");
        break;
    default:
        break;
    }
}

void app_wifi_sta_start(const char *ssid, const char *passwd)
{
    if (tal_wifi_init(wifi_event_callback) != OPRT_OK) {
        TAL_PR_ERR("tal_wifi_init failed");
        return;
    }
    if (tal_wifi_set_work_mode(WWM_STATION) != OPRT_OK) {
        TAL_PR_ERR("set station mode failed");
        return;
    }
    tal_wifi_station_connect((SCHAR_T *)ssid, (SCHAR_T *)passwd);
}
```

## SoftAP (summary)

From `example_os_wifi_ap.c`:

1. `tal_wifi_init(cb)`
2. set AP work mode
3. fill `NW_IP_S` (ip/mask/gw) + SSID/password/channel
4. `tal_wifi_ap_start(...)` (exact prototype in demo / `tal_wifi.h`)
5. optional: `tal_net_socket_create` + `tal_net_send_to` for LAN broadcast

## Scan (summary)

`tal_wifi_all_ap_scan(&ap_list, &count)` then print SSID/RSSI/auth; always
`tal_wifi_release_ap(ap_list)` when done.

## Low power (summary)

After STA is up: `tal_wifi_set_lps_dtim(...)`, `tal_wifi_lp_enable()`, and
platform CPU LP helpers (`tal_cpu_set_lp_mode` / `tal_sleep`) as in the LP demo.
Disable LP before heavy traffic.

## Rules

1. **Open the matching demo `.c` in-tree** when present; copy event handling and struct field names for this SDK version.
2. **Never commit real passwords** from chat into source without user OK; use config / macros the app already uses.
3. **Product vs raw Wi-Fi:** many commercial apps already init Wi-Fi inside TuyaOS product/device init. Grep the app for `tal_wifi_init` / `tuya_iot_*` first.
4. **FFC remotes** use `tuya_iot_wifi_ffc_init/control/bind/send` — different stack; read `service_ffc_*` READMEs.
5. Build with **`tuyaos-build`**. Not TuyaOpen `tos.py` / lwIP-only examples from other trees.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| No `WFE_CONNECTED` | wrong SSID/pass / 5 GHz-only AP on 2.4-only chip | verify band + credentials |
| Double init crash | product stack already called `tal_wifi_init` | reuse existing callback path |
| No IP fields compile | SDK uses `nwipstr` vs `.ip` | match demo `#ifdef` style |
| Scan leaks | forgot `tal_wifi_release_ap` | free after use |