fridge_tracker

# Tool List Sync fridge ingredients, freshness days, and expiration reminders to a low-power e-ink display. This repository provides a complete replicable solution: browser-based ingredient management, Node.js server, ESP32-C3 / ESP32-S3 firmware, three-color / four-color e-ink display rendering, and 4.2-inch and 7.2-inch 3D printed enclosures. You can use our hosted service directly, only making hardware, or deploy the server on your home computer, NAS, or cloud server.  ## What can it do - Record ingredients, purchase dates, freshness days, quantities, and categories in a mobile H5 app. - Automatically calculate expiration status, prioritizing expired and near-expiration ingredients. - ESP32 periodically connects to the internet to fetch new frames, skipping refreshes if no changes occur, and then enters deep sleep. - Supports portrait and landscape orientations, as well as 4.2-inch three-color and 3.97 / 7.5-inch four-color e-ink displays. - Optional use of a built-in text assistant or MCP for agents to query and manage ingredients. - Each account's ingredients, devices, access tokens, and model configurations are isolated. ## How it works ```text Mobile / computer browser Add ingredients, view status, generate one-time pairing code │ ▼ XianZhiTie server (public hosting / local computer or NAS / self-owned cloud server) Save data → generate PNG and native binary frames adapted to the screen → judge frame changes via ETag │ ▼ ESP32-C3 or ESP32-S3 Periodic wake-up → connect to Wi-Fi → download new frame → refresh e-ink display → deep sleep ``` Chinese typesetting, icon and color conversions are completed on the server, and the ESP32 only handles network configuration, downloading, and screen refreshing. Therefore, updating the page layout usually does not require implementing font typesetting on the microcontroller. ## Choose your approach | Approach | What you need to prepare | Service address | Suitable for | | --- | --- | --- | --- | | Use public hosting service (recommended for beginners) | Make and flash hardware | `https://fridge.followllm.online` | Want to make a finished product quickly, no need to maintain a server | | Local network deployment | Hardware + a constantly on computer or NAS | e.g., `http://192.168.0.101:8788` | Data stored at home, devices can only sync on the same network | | Self-owned cloud server deployment | Hardware + Node.js server + HTTPS domain | Your HTTPS address | Need cross-network sync and full control of the service | | Experience software only | Browser | Public hosting or local `127.0.0.1` | Preview H5 and screen before deciding to buy hardware | Public hosting service is not a must for making hardware. Firmware, protocol, server, and database are all in this repository, and the three deployment methods use the same device pairing and frame fetching process. ## Hardware list First, make a USB-powered desktop prototype, and confirm the screen can refresh before considering batteries, switches, and enclosures. ### Essential - A development board (choose one): - `ESP32-C3 Super Mini`: small size, low cost, no PSRAM, can use the project's block refresh solution. - `ESP32-S3 N16R8`: more memory, suitable for further expansion. - A supported SPI e-ink display and matching driver / adapter board (choose one): - `GDEY042Z98` / `E042A13`: 4.2-inch, 400 × 300, three-color black, white, and red. - `GDEM0397F81`: 3.97-inch, 800 × 480, four-color black, white, yellow, and red. - `GDEM075F52`: 7.5-inch, 800 × 480, four-color black, white, yellow, and red. - USB cable, reliable 5V USB power supply, and connecting wires. - A computer that can run Arduino IDE 2.x. - Available 2.4 GHz Wi-Fi; ESP32 cannot connect to 5 GHz networks only. ### Optional - 3D printed enclosure, screws, and installation accessories. - Battery, charging and discharging module, and power switch. Different modules have different electrical parameters; the repository's enclosure electronic package cannot replace power design. It is recommended to use USB power for the first debugging. - A constantly on computer, Raspberry Pi, or NAS for local deployment of the server. - Self-owned domain and HTTPS reverse proxy for public deployment. - OpenAI-compatible model API Key, only needed when using the built-in text assistant; displaying ingredients does not require. > [!IMPORTANT] > The voltage requirements of the e-ink display, driver board, and development board may be different. The current wiring table is written according to the 3.3V SPI adapter board used in this project; please check the screen and adapter board information before wiring, and do not connect 5V logic signals directly to devices that only accept 3.3V. ## Make from scratch: follow this order ### Step 1: Experience the page and decide on the screen Open [public hosting service](https://fridge.followllm.online), register an account, add a few ingredients, and switch to the "Devices" page to view screen previews in different panel and orientation settings. This allows you to confirm the desired 4.2-inch three-color or larger four-color version before purchasing or wiring. If you do not want to use the public service, you can skip to [Step 3](#step-3-optional-run-the-server-locally). ### Step 2: Connect ESP32 and e-ink display The firmware supports both C3 and S3, but the pinouts are different: | E-ink display adapter board | ESP32-C3 Super Mini | ESP32-S3 N16R8 | | --- | --- | --- | | `GND` | `GND` | `GND` | | `3V3` / `VCC` | `3V3` | `3V3` | | `SCK` / `CLK` | GPIO4 | GPIO12 | | `SDA` / `DIN` / `MOSI` | GPIO6 | GPIO11 | | `RST` / `RES` | GPIO5 | GPIO7 | | `DC` | GPIO3 | GPIO8 | | `CS1` / `CS` | GPIO7 | GPIO10 | | `BUSY` | GPIO10 | GPIO9 | | `CS2`, `MISO` | Not connected | Not connected | The `SDA` on the adapter board is the SPI `MOSI` here, not I²C. C3 is recommended to avoid GPIO20 / GPIO21 and keep the antenna away from the screen cable and metal enclosure. For more complete board settings, memory strategies, and troubleshooting logs, see [firmware instructions](esp32_epaper_fridge_tracker/README.md). ### Step 3 (optional): Run the server locally If you directly use the public hosting service, skip to Step 4. Local service requires Node.js 22.5 or higher: ```sh cd fridge_tracker_server npm install npm run install:browsers cp config.example.json config.json npm start ``` Open the browser at `http://127.0.0.1:8788`. By default, only local access is allowed; to let ESP32 connected under the same Wi-Fi access the service, change `host` in `config.json` to `0.0.0.0`, replace the example password and key, and restart the service. On Mac, query the local network address: ```sh ipconfig getifaddr en0 ``` If the output is `192.168.0.101`, the service address in the device pairing webpage should be filled with `http://192.168.0.101:8788`, not `127.0.0.1`. For Linux, NAS, public HTTPS, database, and reverse proxy precautions, see [server instructions](fridge_tracker_server/README.md). ### Step 4: Choose the screen and flash the firmware Open `esp32_epaper_fridge_tracker/esp32_epaper_fridge_tracker.ino` with Arduino IDE. 1. Install Espressif's `esp32` development board package in Arduino IDE's Boards Manager; install `GxEPD2` and `Adafruit GFX Library` in Library Manager. 2. Open `esp32_epaper_fridge_tracker/Config.h`, modify only `FRIDGE_PANEL_TYPE` to the value corresponding to the actual screen. 3. Choose the actual development board in Arduino IDE's `Tools → Board`, do not manually modify `BoardProfile.h`. 4. Open the serial monitor with a baud rate of `115200`, compile, and upload. | Actual screen | `FRIDGE_PANEL_TYPE` | | --- | --- | | GDEM075F52 | `FRIDGE_PANEL_GDEM075F52` | | GDEM0397F81 | `FRIDGE_PANEL_GDEM0397F81` | | GDEY042Z98 / E042A13 | `FRIDGE_PANEL_GDEY042Z98` | | Development board | Arduino IDE Board | Key settings | | --- | --- | --- | | ESP32-C3 Super Mini | `Nologo ESP32C3 Super Mini` | 4MB Flash; No OTA (2MB APP/2MB FATFS); USB CDC Enabled | | ESP32-S3 N16R8 | `ESP32S3 Dev Module` | 16MB Flash; 3MB APP / 9.9MB FATFS; OPI PSRAM; USB CDC Enabled | The accurate Arduino IDE / CLI commands and dependencies are in [firmware instructions](esp32_epaper_fridge_tracker/README.md#arduino-ide-and-cli). ### Step 5: Generate a one-time pairing code Log in to the H5 in your chosen service: - Public hosting: `https://fridge.followllm.online` - Local service: `http://127.0.0.1:8788` Enter the "Devices" page, select the screen model and orientation consistent with the firmware, and generate a one-time pairing code. ### Step 6: Configure the device network and bind The firmware will create a Wi-Fi hotspot named `XianZhiTie-xxxxxx` on its first startup: 1. Connect to this hotspot with your mobile phone. 2. Open the browser at `http://192.168.4.1`. 3. Fill in your home 2.4 GHz Wi-Fi and password. 4. Fill in the service address: public hosting address, local network address, or your HTTPS address. 5. Fill in the generated one-time pairing code, select orientation and check interval, and save. After the device restarts, it will register with the service, download the first frame, refresh the screen, and hibernate. For existing devices that need reconfiguration, hold down BOOT (GPIO0) to reset and clear NVS and cache frames; normal power-off and then power-on will also temporarily open the configuration hotspot after this round of frame checks. ### Step 7: Confirm the complete link Add or modify an ingredient in H5, wait for the device to check next, or restart to trigger the check. When successful, you should see: - The device appears on the "Devices" page, showing the recent sync time. - The serial log first displays the Wi-Fi address and registration success, then displays `Stored frame bytes`. - The frame size for the 4.2-inch three-color display is `30000` bytes; for the two four-color displays, it is `96000` bytes. - The screen displays new ingredients, and then the log shows the screen hibernation and ESP32 deep sleep. - If the ingredients do not change, the service returns `304`, and the device does not refresh, which is normal power-saving behavior. If the hotspot is not found, the frame does not update, or the color is abnormal, first determine where the problem occurs in the network configuration, registration, download, or screen refreshing stage, and then check [firmware log and troubleshooting instructions](esp32_epaper_fridge_tracker/README.md#configuration-entry-and-operation-log). ### Step 8 (optional): Print the enclosure and complete assembly - 4.2-inch version: open [`models/ink_frame_v1/ink_frame_assembly.step`](models/ink_frame_v1/ink_frame_assembly.step) to view the complete assembly, and see [4.2-inch enclosure instructions](models/ink_frame_v1/README.md) for printing files, parameterized source code, physical measurements, and large model CAD workflow. - 7.2-inch version: directly open [`models/epaper_enclosure_7_2/冰箱显示屏.3mf`](models/epaper_enclosure_7_2/冰箱显示屏.3mf) with Bambu Studio, and see [7.2-inch enclosure instructions](models/epaper_enclosure_7_2/README.md) for structure, printing parameters, and MakerWorld address. The screen, driver board, battery, and interface positions may vary between batches. Use the existing enclosure as a reference, and measure with a caliper before printing to ensure the screen installation slot, visible window, FPC, Type-C, switch, and highest electronic component positions. ## Deployment details ### Using our hosted service The public address is `https://fridge.followllm.online`. Here, you only need to register an account, generate a pairing code, and do not need to install Node.js, database, or browser rendering dependencies. Each account's data is isolated. Basic ingredient management and e-ink display synchronization do not require model configuration. The API Key, model ID, and Base URL used by the built-in assistant are set by each user in "User → My Model", and the costs and quotas are attributed to the user. ### Deploy on local computer or NAS The service and SQLite data are all stored on your own device. The ESP32 and server usually need to be on the same local network, and the computer or NAS running the service needs to be online during device synchronization. This approach does not require a domain or HTTPS, but do not expose the unencrypted local HTTP port to the public network. ### Deploy on your public server The server can run on a Linux host supporting Node.js 22.5+ and Chromium. For formal deployment, at least: - Use an independent `config.json` and new administrator password, device token, and credential encryption key. - Persist `fridge_tracker_server/data/`, and perform SQLite backups. - Use Caddy, Nginx, or a hosting platform entry to provide HTTPS. - Ensure Playwright Chromium and its system dependencies are installed. - Do not publicly expose the local demo account, demo token, or unencrypted MCP HTTP endpoint. More configuration fields, user isolation, MCP, and agent instructions are in [server README](fridge_tracker_server/README.md), and the main README only retains the path to complete the hardware. ## Repository directory | Directory | Content | Continue from here | | --- | --- | --- | | `fridge_tracker_server/` | H5, API, SQLite, account, MCP, agent, three-color / four-color frame rendering | [Server README](fridge_tracker_server/README.md) | | `esp32_epaper_fridge_tracker/` | C3 / S3 unified firmware, network configuration, registration, frame fetching, hibernation, screen driver | [Firmware README](esp32_epaper_fridge_tracker/README.md) | | `models/ink_frame_v1/` | 4.2-inch parameterized CAD, STEP, STL, 3MF, and design inspection | [4.2-inch enclosure README](models/ink_frame_v1/README.md) | | `models/epaper_enclosure_7_2/` | 7.2-inch STEP assembly, Bambu Studio 3MF, and physical preview | [7.2-inch enclosure README](models/epaper_enclosure_7_2/README.md) | ## Modification and verification Server commands run in `fridge_tracker_server/`: ```sh npm run dev npm run check npm test ``` When modifying expiration calculation, sorting, authentication, device ownership, or frame generation, add corresponding `node:test` tests. After modifying the 4.2-inch enclosure size, fit, hole, or fastening structure, run: ```sh python models/ink_frame_v1/design_checks.py ``` Then re-export and check the complete assembly, front frame, and back shell STEP. Detailed development conventions see `AGENTS.md`. ## Security reminders - Do not submit `fridge_tracker_server/config.json`, `fridge_tracker_server/data/`, `.env*`, generated frame binary files, or build products. - When providing services externally, replace all example passwords and tokens, and use HTTPS. - Personal model API Key should not be written to the repository; the page will encrypt and save by account. - The current repository does not contain a license file; please confirm the subsequent license instructions before copying, modifying, or redistributing.