{"id":23069999,"url":"https://github.com/steakunderscore/pixel-portal","last_synced_at":"2026-02-19T02:01:08.257Z","repository":{"id":267750244,"uuid":"902230018","full_name":"steakunderscore/pixel-portal","owner":"steakunderscore","description":"A Christmas coding challenge using an ESP32-S3-Matrix display board. Involes a Cloud Run service to update pixels via a WebSockets, enabling remote control of the LED matrix display.","archived":false,"fork":false,"pushed_at":"2024-12-12T07:52:01.000Z","size":415,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-20T05:56:54.459Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/steakunderscore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-12T06:55:56.000Z","updated_at":"2025-01-23T19:55:07.000Z","dependencies_parsed_at":"2024-12-12T08:30:01.793Z","dependency_job_id":null,"html_url":"https://github.com/steakunderscore/pixel-portal","commit_stats":null,"previous_names":["steakunderscore/pixel-portal"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/steakunderscore/pixel-portal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steakunderscore%2Fpixel-portal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steakunderscore%2Fpixel-portal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steakunderscore%2Fpixel-portal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steakunderscore%2Fpixel-portal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/steakunderscore","download_url":"https://codeload.github.com/steakunderscore/pixel-portal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steakunderscore%2Fpixel-portal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29600841,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T00:59:38.239Z","status":"online","status_checked_at":"2026-02-19T02:00:07.702Z","response_time":117,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-16T06:18:20.039Z","updated_at":"2026-02-19T02:01:08.226Z","avatar_url":"https://github.com/steakunderscore.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pixel Portal\n\n| display                                             | web interface                                            |\n| --------------------------------------------------- | -------------------------------------------------------- |\n| ![Pixel Portal display](docs/img/running-photo.jpg) | ![Pixel Portal web interface](docs/img/webinterface.png) |\n\n## Overview\n\nA creative implementation of a Christmas coding challenge using an ESP32-S3-Matrix display board. The project connects to a Cloud Run service to receive pixel data through WebSockets, enabling remote control of the LED matrix display.\n\nThe system consists of three components: a web interface, a backend service, and an ESP32-S3-Matrix display board. The backend runs on GCP Cloud Run, and the display connects to the backend through a WebSocket connection over WiFi.\n\n## Features\n\n- Real-time pixel updates via WebSocket\n- Web-based interface for drawing\n- ESP32 LED matrix display integration\n- Cloud-hosted backend with automatic scaling\n- Multi-user support\n\n## Usage\n\n1. Access the web interface at [https://pixel-portal-xpv3wpdyrq-ew.a.run.app](https://pixel-portal-xpv3wpdyrq-ew.a.run.app/)\n2. Click to draw pixels\n3. Changes appear instantly on connected displays\n\nYou can also view the websocket data using the [listener page](https://pixel-portal-xpv3wpdyrq-ew.a.run.app/listener.html)\n\n## Hardware Requirements\n\n- [Waveshare ESP32-S3-Matrix](https://www.waveshare.com/esp32-s3-matrix.htm)\n- USB-C cable for programming\n\n## Prerequisites\n\n- VS Code with ESP-IDF extension - For building firmware\n- Google Cloud SDK - For pushing continer images and setting up infrastructure\n- GCP account - For running the Cloud Run service\n- Podman - For building container images\n- Terraform - For infra seutp\n\n## Setup and deployment\n\nTo run the project the backend needs to be runing. I've used GCP Cloud Run, but it could be anwhere. The Firmware needs to be written to to the ESP32. For this I've used VScode and ESP-IDF.\n\n## Building and Flashing Firmware\n\n1. Setup VScode with insalling the ESP-IDF extension\n2. Setup wifi and certs\n   a. `cp firmware/main/secrets.h.example firmware/main/secrets.h` and update `firmware/main/secrets.h`\n   b. Generate updated CA certs file by running `cd firmware \u0026\u0026 firmware/scripts/get_ca_cert.sh`\n3. Build using `idf.py build`. This should:\n   a. Download the components I've used\n   b. Compile all the different binaries required\n4. Flash to the ESP32 with `idf.py flash`\n\n### Deploying backend\n\n1.  Within the backend path `cd backend`\n2.  Build backend image `podman build -t pixel-portal .`\n3.  Push image `podman push localhost/pixel-portal:latest europe-west1-docker.pkg.dev/pixel-project-d6a7/pixel-portal-repo/pixel-portal:v0.0.1-manual3`\n4.  Move to terraform folder `cd terraform`\n5.  Update TF to use new image `vim main.tf`\n6.  Apply TF `terraform apply`\n\n## Architecture\n\nA fairly strightforwad setup where the users interact with the web interface. Which talks to the backend over a websocket. The ESP32 also listens for updates from the websocket. The backend doesn't hold any state, just broadcasts the pixel updates to all websocket clients.\n\n![Architecture diagram](docs/img/architecture.drawio.png)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteakunderscore%2Fpixel-portal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteakunderscore%2Fpixel-portal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteakunderscore%2Fpixel-portal/lists"}