{"id":23532464,"url":"https://github.com/whiteshadow1234/petcam","last_synced_at":"2025-06-16T19:06:13.121Z","repository":{"id":268710865,"uuid":"905225476","full_name":"whiteSHADOW1234/PetCam","owner":"whiteSHADOW1234","description":"A real-time pet camera application that allows users to remotely monitor and interact with their pets using a web browser, with video streamed from a designated client device to a central server and displayed on a dedicated viewing page.","archived":false,"fork":false,"pushed_at":"2025-02-10T17:06:15.000Z","size":131,"stargazers_count":12,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T19:23:03.822Z","etag":null,"topics":["browser-based","esp32","iot","monitor","monitoring-tool","pet-project","real-time-communication","webrtc","websockets"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/whiteSHADOW1234.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-18T12:04:18.000Z","updated_at":"2025-03-17T10:33:03.000Z","dependencies_parsed_at":"2024-12-18T13:28:57.040Z","dependency_job_id":"286845df-3db8-4947-bb13-c136ac53c633","html_url":"https://github.com/whiteSHADOW1234/PetCam","commit_stats":null,"previous_names":["whiteshadow1234/petcam"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteSHADOW1234%2FPetCam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteSHADOW1234%2FPetCam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteSHADOW1234%2FPetCam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteSHADOW1234%2FPetCam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whiteSHADOW1234","download_url":"https://codeload.github.com/whiteSHADOW1234/PetCam/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250333113,"owners_count":21413331,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["browser-based","esp32","iot","monitor","monitoring-tool","pet-project","real-time-communication","webrtc","websockets"],"created_at":"2024-12-25T23:10:44.234Z","updated_at":"2025-04-22T22:25:42.610Z","avatar_url":"https://github.com/whiteSHADOW1234.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PetCam: Your Remote Real-time Pet Monitoring Solution\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"README_zh_tw.md\"\u003e\u003cstrong\u003e中文 README\u003c/strong\u003e\u003c/a\u003e | \n    \u003ca href=\"esp_idf_esp32s3/README_hardware.md\"\u003e\u003cstrong\u003eESP32-S3 Firmware Guide\u003c/strong\u003e\u003c/a\u003e | \n    \u003ca href=\"esp_idf_esp32s3/README_hardware_zh_tw.md\"\u003e\u003cstrong\u003eESP32-S3 設定指南\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nThis project implements a real-time pet camera application with the following features:\n\n*   **Webcam Streaming:** Captures and streams live video from a designated webcam-equipped device using WebRTC.\n*   **Remote Viewing:** Allows you to view the live stream from any device on your local network through a web browser.\n*   **Remote Pan Control:** Enables remote control of a pan mechanism (using an ESP32-S3, stepper motor, and joystick) to change the camera's viewing direction.\n*   **Talk to Pet:** Functionality to enable the viewer to transmit their voice to the pet through the webcam device.\n*   **HTTPS:** Uses HTTPS to ensure secure communication.\n*   **Repurpose Unused Smartphones:**  With the increasing number of unused smartphones in many households, this project provides a practical way to repurpose these devices as remote webcams, reducing electronic waste and providing added value.\n\n## Project Structure\n\n```\npet-camera-project/\n├── client/                     # Client-side code (web applications)\n│   └── open-cam/               # Web application for the camera device\n│       ├── index.html          # HTML for the open-cam page\n│       ├── script.js           # JS for camera access, WebRTC, and streaming\n│       └── style.css           # CSS for open-cam page styling\n│   └── server-view/\n│       └── script.js           # JS for WebRTC receiving logic and motor control\n├── esp_idf_esp32s3/            # ESP32-S3 firmware (motor control)\n│   ├── .devcontainer/          # Dev container configuration (for development)\n│   ├── test/                   # Test files for individual components\n│   └── main/                   # Main source code for ESP32-S3\n│       ├── CMakeLists.txt      # CMake build configuration\n│       ├── http.cpp/http.h     # HTTP server logic\n│       ├── joystick.cpp/joystick.h # Joystick input handling\n│       ├── main.cpp            # Main program entry point\n│       ├── wifi.cpp/wifi.h     # Wi-Fi connection management\n│       ├── wifi_config.h       # Wi-Fi credentials (configure this!)\n│       └── ULN2003.cpp/ULN2003.h # 28BYJ-48 stepper motor control\n└── server/                     # Server-side code (Node.js)\n    ├── server.js               # Node.js server with WebRTC signaling\n    ├── key.pem                 # SSL private key (self-signed for testing)\n    └── cert.pem                # SSL certificate (self-signed for testing)\n    └── templates/\n        ├── index.html          # Server landing page\n        └── server-view.html   # Web page to view stream and control camera\n```\n\n## Hardware\n\n*   **Webcam Device:** A laptop or computer with a built-in or connected webcam.\n*   **Server:** A computer (can be the same as the webcam device for testing) to run the Node.js server.\n*   **ESP32-S3 Development Board:**\n    *   Model: **Goouuu ESP32-S3 N16R8** (16MB flash/8MB PSRAM, dual Type-C USB, W2812 RGB).\n    *   Used for controlling the stepper motor and handling HTTP requests for motor control.\n       ![Image Source](https://www.taiwansensor.com.tw/wp-content/uploads/2023/12/O1CN01Zmz8W21kAXm0aySdE_672934643.jpg)\n*   **28BYJ-48 Stepper Motor with ULN2003 Driver Board:**\n    *   Used for panning the camera.\n       ![Image Source](https://m.media-amazon.com/images/I/61Ml9ebd2kL._AC_UF894,1000_QL80_.jpg)\n*   **Joystick Module:**\n    *   Used to control the direction of the stepper motor.\n       ![Image Source](https://down-br.img.susercontent.com/file/bcf905ecd9ff177fde7f4fbcafc9c400)\n*   **Power Supply Module:**\n    *   Dedicated power supply for the stepper motor (requires 7-12V DC).\n       ![Image Source](https://http2.mlstatic.com/D_613161-MLA47599398871_092021-C.jpg)\n\n## Software Prerequisites\n\n*   **Node.js and npm:** Install Node.js and npm from [link](https://nodejs.org/).\n*   **OpenSSL:** Used to generate a self-signed certificate. Usually pre-installed on Linux/macOS. For Windows, it can be installed with Git for Windows or separately. Verify with `openssl version`.\n*   **VS Code with ESP-IDF Extension:** Follow the instructions here to install the ESP-IDF extension for VS Code: [link](https://marketplace.visualstudio.com/items?itemName=espressif.esp-idf-extension)\n*   **Git:** Install Git for version control: [link](https://git-scm.com/)\n*   **Web Browser:** A modern web browser with WebRTC support (e.g., Brave, Firefox, or Edge, **but not Chrome**).\n\n## Installation and Setup\n\n**1. Clone the Repository:**\n\n```bash\ngit clone https://github.com/whiteSHADOW1234/PetCam.git\ncd PetCam\n```\n\n**2. Server Setup:**\n\n*   **Install Node.js Dependencies:**\n    ```bash\n    npm install  # Execute this command in the `PetCam` directory\n    ```\n\n*   **Generate Self-Signed Certificate:**\n    *   Run this command in the `server` directory, **replacing `192.168.1.10` with your server's actual LAN IP address**:\n\n        ```bash\n        openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes -subj \"/C=US/ST=CA/L=San Francisco/O=MyOrg/CN=192.168.1.10\" -addext \"subjectAltName=IP:192.168.1.10,DNS:localhost,IP:127.0.0.1\" -addext \"extendedKeyUsage=serverAuth\"\n        ```\n\n**3. ESP32-S3 Setup (Motor Control):**\n\n*   **Configure Wi-Fi:**\n    *   **Option 1: `wifi_config.h`:**\n        *   Create a file named `wifi_config.h` inside the `esp_idf_esp32s3/main` directory.\n        *   Add the following content, replacing placeholders with your actual Wi-Fi credentials:\n\n            ```c\n            #ifndef WIFI_CONFIG_H\n            #define WIFI_CONFIG_H\n\n            #define EXAMPLE_ESP_WIFI_SSID \"YOUR_WIFI_SSID\"\n            #define EXAMPLE_ESP_WIFI_PASS \"YOUR_WIFI_PASSWORD\"\n\n            #endif\n            ```\n\n    *   **Option 2: Modify `wifi.cpp`:**\n        *   Directly edit the `esp_idf_esp32s3/main/wifi.cpp` file.\n        *   Comment out or remove the line `#include \"wifi_config.h\"`.\n        *   Set the `EXAMPLE_ESP_WIFI_SSID` and `EXAMPLE_ESP_WIFI_PASS` defines within `wifi.cpp` to your Wi-Fi credentials.\n\n*   **Build and Flash the Firmware:**\n    1. **Set Espressif Device Target:**\n        *   In VS Code, press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS).\n        *   Type `ESP-IDF: Set Espressif Device Target` and press Enter.\n        *   Select `esp32s3` and choose the first option: `ESP32-S3 chip (via builtin USB-JTAG)`.\n    2. **Set Serial Port:**\n        *   Press `Ctrl+Shift+P` (or `Cmd+Shift+P`).\n        *   Type `ESP-IDF: Select Port to Use` and press Enter.\n        *   Select the serial port corresponding to your ESP32-S3 board.\n    3. **Build, Flash, and Monitor:**\n        *   Press `Ctrl+Shift+P` (or `Cmd+Shift+P`).\n        *   Type `ESP-IDF: Build, Flash and Start a Monitor on your Device` and press Enter.\n        *   This will build the firmware, flash it to the ESP32-S3, and open the serial monitor to view output.\n\n**4. Wiring:**\n\n*   **28BYJ-48 Stepper Motor (using ULN2003 driver):**\n\n    | 28BYJ-48 | ULN2003 | ESP32-S3/Power Module |\n    | -------- | ------- | ---------------------- |\n    | Red      | +       | 5V (Power Module)      |\n    | Orange   | IN1     | GPIO15                |\n    | Yellow   | IN2     | GPIO16                |\n    | Pink     | IN3     | GPIO17                |\n    | Blue     | IN4     | GPIO18                |\n    | Black    | -       | GND (Power Module)     |\n\n*   **Joystick Module:**\n\n    | Joystick | ESP32-S3 |\n    | -------- | -------- |\n    | VCC      | 3.3V     |\n    | GND      | GND      |\n    | VRx      | GPIO1    |\n    | VRy      | GPIO2    |\n    | SW       | GPIO4    |\n\n**Note:**\n\n*   The specific GPIO numbers for the ESP32-S3 might vary depending on the development board you are using. Refer to your board's pinout diagram.\n*   Make sure the VRx and VRy pins of the joystick are connected to GPIO pins that support ADC (Analog-to-Digital Conversion).\n\n## Running the Application\n\n1. **Start the Server:**\n\n    ```bash\n    npm start # execute this command in the `PetCam` directory\n    ```\n\n    The server console will output the accessible URLs, including the LAN IP addresses for `open-cam` and `server-view`.\n\n2. **Access Open-Cam (Webcam Client):**\n\n    *   Open a web browser on the device with the webcam.\n    *   Go to `https://\u003cserver_lan_ip\u003e:5000/client/open-cam`, replacing `\u003cserver_lan_ip\u003e` with one of the server's LAN IP addresses listed in the console output.\n    *   Grant the website permission to access your camera and microphone when prompted.\n\n3. **Access Server-View:**\n\n    *   Open a web browser on any device on your LAN.\n    *   Go to `https://\u003cserver_lan_ip\u003e:5000/server-view`, replacing `\u003cserver_lan_ip\u003e` with the server's LAN IP address.\n    *   You should see the video stream from the `open-cam` device.\n\n4. **Controlling the Motor:**\n    *   Use the joystick connected to the ESP32-S3 to control the direction of the stepper motor.\n    *   Click the \"Talk to Pet\" button on the `server-view` page to enable audio from the viewer to the `open-cam` device.\n\n## Troubleshooting\n\n*   **Camera Not Starting on Open-Cam:**\n    *   Check browser and OS permissions for camera and microphone access.\n    *   Verify that the `serverAddress` in `client/open-cam/script.js` is correct.\n    *   Look for errors in the browser's developer console (F12).\n    *   Ensure no other applications are using the camera.\n    *   Try a different browser or device.\n\n*   **No Video on Server-View:**\n    *   Examine the console logs on the server, `open-cam`, and `server-view` for errors.\n    *   Check the \"Network\" tab in the `server-view` browser's developer tools to see if the offer, answer, and ICE candidates are being exchanged.\n    *   Verify that the `RTCPeerConnection` on `server-view` is established and the `ontrack` event is firing.\n\n*   **Motor Not Responding:**\n    *   Check the wiring between the ESP32-S3, motor driver, and joystick.\n    *   Verify that the ESP32-S3 is connected to your Wi-Fi network.\n    *   Use the serial monitor in VS Code to see if the ESP32-S3 is receiving commands.\n\n*   **Server Not Accessible:**\n    *   Double-check your server's LAN IP address.\n    *   Make sure the server is running and listening on port 5000.\n    *   Check your firewall settings (allow port 5000).\n\n*   **SSL Errors:**\n    *   If you see SSL errors, it's because you're using a self-signed certificate. You'll need to add a temporary exception in your browser to proceed during development. **For production, use a valid certificate from a trusted Certificate Authority.**\n\n*   **Refresh:** If you make changes to the code, restart the server and hard refresh (Ctrl+Shift+R or Cmd+Shift+R) the web pages.\n\n## `esp_idf_esp32s3/test` Folder Usage\n\nThe `test` folder contains code for testing individual components:\n\n*   **`joystick_motor.cpp`:** Tests joystick control of the stepper motor.\n\n**To use a test file:**\n\n1. Copy the contents of the `.cpp` file from the `test` folder into `esp_idf_esp32s3/main/main.cpp`.\n2. Build, flash, and monitor the ESP32-S3 using the ESP-IDF extension in VS Code.\n\n## Important Notes\n\n*   **Repurposing Smartphones:** This project provides a great way to utilize old or unused smartphones as webcams, reducing electronic waste and giving them a new purpose.\n*   **HTTPS:** HTTPS is required for accessing `getUserMedia` in most browsers. The self-signed certificate is for development only.\n*   **Performance:** This project uses a simple WebRTC implementation for testing. Performance might be limited, especially with multiple clients. Consider using a dedicated media server for production.\n*   **Audio:** The audio in this project is unidirectional from the `server-view` to the `open-cam`. Implementing bi-directional audio requires further development.\n*   **Scalability:** For a large number of clients, you'll need a more scalable solution, potentially involving a media server.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhiteshadow1234%2Fpetcam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhiteshadow1234%2Fpetcam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhiteshadow1234%2Fpetcam/lists"}