t-embed-insecam-widget/README.md

insecam desk widget (LilyGO T-Embed)

A little window onto the world's public webcams. The T-Embed's 320×170 IPS screen shows a random camera from insecam.org or opentopia.com — as live MJPEG video where the camera streams it — and moves on to the next one every 20 seconds. The knob steps through cameras, the LED ring drains as the countdown runs. Everything happens on the ESP32-S3; no bridge or PC needed.

Both sites list cameras that are reachable on the public internet without any password (opentopia leans towards harbours, ski slopes and campuses; insecam towards forgotten IP cams). The widget only ever does what a browser on those sites does: fetch a listing page, then fetch the camera's own snapshot/stream URL.

Hardware

Either LilyGO T-Embed. The firmware tells them apart at boot by probing the I2C bus (ES7210 on the 2022 board, BQ27220/BQ25896/PN532 on the CC1101 board) and picks the matching pin map from main/board.c. Nothing beyond the board is needed: ESP32-S3R8, 16 MB flash, 8 MB PSRAM, ST7789 170×320, EC11 encoder, APA102 (×7) or WS2812 (×8) ring. Printable shells for the original board are in LilyGO's repo under Shell_file/.

Build and flash

Needs ESP-IDF 5.5 (on this machine: . ~/esp/idf55-env.sh).

idf.py set-target esp32s3
idf.py build
idf.py -p /dev/ttyACM0 flash monitor

The partition table keeps nvs where the ESPHome build that shipped on this unit had it (0xf90000), so stored Wi-Fi credentials survive re-flashing. First-boot defaults (interval, listing, brightness, forced variant) live under idf.py menuconfig → insecam desk widget; the on-device menu overrides them and stores its choices in NVS.

First boot / Wi-Fi

With no saved network the widget opens the open hotspot insecam-setup; join it with a phone and the captive portal (or http://192.168.4.1) asks for your Wi-Fi. Holding the knob down while the widget starts forces the portal.

Controls

input	action
turn clockwise	next camera
turn counter-clockwise	previous camera (history of 24)
click	pause / resume the countdown (the live stream keeps playing)
double-click	hide / show the caption
hold	open the menu (hold again, or Close, to leave it)

In the menu: turn to move (the list wraps around), click to select or toggle, click a number to edit it (turn changes it, click confirms), hold to go back. Entries:

• Save as favourite / Remove from favourites — the camera that was playing; saving asks for one of the 50 slots (it jumps to the first empty one; picking a used slot overwrites it).
• Favourites — the saved cameras; click one to play it. A saved camera shows a yellow FAV n marker while it plays.
• Source — Random draws random listing pages, Popular walks the sites' top-rated listings in rank order from the top, Favourites cycles the saved slots.
• Provider — insecam, opentopia or Mixed (a random site per batch).
• Time per camera, Listing (mixed / top rated / newest), Screen brightness, Ring brightness, Caption.
• Theme — the look of the menu, boot page and pop-ups, applied as you cycle: Phosphor (green), Pink, Amber, Ice, and Terminal (green with an 8×16 pixel font). The camera caption keeps its own neutral style.
• Forget a favourite, Wi-Fi setup (reboots into the hotspot), Power off, the board name with its IP, and the power source.

Power off switches the peripheral rail off (screen, ring, codec) and puts the ESP32-S3 into deep sleep; turning the knob wakes it and it boots as normal. The encoder's push button is deliberately not a wake source: it is GPIO 0, and a press that is still held when the chip resets would land it in the ROM bootloader instead.

The menu closes by itself after 45 s without input.

Battery

The original board has no fuel gauge, only a 100 k/100 k divider on the supply rail (GPIO 4). On USB that rail sits at ~4.4 V (5 V minus a Schottky drop), so anything above 4.25 V is reported as USB powered; below that it is the cell voltage, turned into a rough percentage from a LiPo discharge table. While on battery the caption bar shows a small battery glyph with the percentage; on USB it stays out of the way. The CC1101 board's BQ27220 gauge is not supported.

LED ring

ring	meaning
white breathing	starting up
purple breathing	waiting in the Wi-Fi setup hotspot
blue dot running round	connecting to a camera
teal, draining	countdown to the next camera
amber, steady	paused
red blinking	camera offline / insecam unreachable, skipping
dim grey	menu open

How it works

• insecam.c fetches one listing page (/en/byrating/ or /en/bynew/, random page) — six cameras per request, so insecam sees one hit every two minutes.
• opentopia.c does the same for opentopia (hiddencam.php, rated or newest), then, just before a camera plays, reads its page in Live Feed mode for the camera's own MJPEG URL (or Current Still when there is no video). The site is HTTPS-only, so those pages go through webpage.c — esp_http_client with the certificate bundle — costing a TLS handshake (~0.7 s) per fetch.
• httpstream.c is a small raw-socket HTTP client: esp_http_client gives up on bodies without Content-Length, which is exactly what MJPEG cameras send.
• jpegframe.c pulls complete JPEG files out of the byte stream by walking the marker structure (so an EXIF thumbnail's EOI can't truncate a frame).
• jpegdec.c decodes with Espressif's esp_new_jpeg, scaling inside the decoder to the smallest multiple-of-8 size that still covers the screen, then bilinear-resamples the remainder to a full-bleed 320×170 (≈100 ms for a 1280×800 frame, so MJPEG streams play at a few fps).
• slideshow.c runs the state machine: connect, play frames until the interval elapses or the knob moves, skip dead cameras, keep history for "previous".
• ui.c is LVGL 9 via esp_lvgl_port: a canvas for the frame, a translucent caption bar, a LIVE/PAUSED badge, a hairline progress bar and a six-row menu page.
• settings.c keeps the settings blob and the 50 favourite slots in NVS (namespace widget); menu.c is the knob-driven menu that edits them; power.c is the deep-sleep power-off with ext1 wake on the encoder pins.

License

MIT — see LICENSE. Pin maps come from LilyGO's T-Embed and T-Embed-PN532 repositories (MIT). esp_new_jpeg is fetched from Espressif's component registry at build time under its own license.