简体中文 | English

Local push lets an application or AI agent on your computer connect directly to NOTE4 over your local network. Display calendars, weather, photos, or study material on the e-paper screen, and use the device's buttons and microphone to interact with the application.

This guide covers device preparation and your first image push. For development APIs, see the public SDK repository.

Supported Device and Firmware

Item Requirement
Device ZECTRIX NOTE4, model zectrix-s3-epaper-4.2
Canvas Full 400 × 300 pixels
Firmware NOTE4 firmware 3.7.2 or later supports local push
Network The computer and device must be able to reach each other on the local network
Device setting Enable “Keep Wi-Fi on in standby” under Settings → Network Sync

This guide does not apply to the NOTE4C four-color development board. Local push is supported on NOTE4 firmware 3.7.2 and later. Use firmware intended for your device model; do not flash firmware for a different model.

What You Can Do

  • Display images: Push monochrome, 4-level grayscale, or 16-level grayscale images for dashboards, photo albums, timetables, and study cards.
  • Handle buttons: Receive Up, Down, and Confirm button events and let your application define actions such as navigation or selection.
  • Add voice interaction: Receive recordings started with the device button, or play audio through the device. Your application supplies speech recognition, text-to-speech, and AI services.
  • Read device status: Query battery level, charging status, and Wi-Fi signal strength. Individual API capabilities depend on the firmware and SDK.

The application runs on your computer or another compatible host; NOTE4 provides the display and interaction. A successful push does not install the application on the device. Continuous updates, button handling, and voice interaction require the host application to remain running.

How It Differs from Cloud Push

Method Connection path Documentation
Local push A local application connects directly to NOTE4 over the LAN This guide and the public SDK
Cloud API An application calls Zectrix Cloud services Cloud API documentation
Mini program Use the mini program for Wi-Fi setup, image push, and other operations Mini Program User Guide

Local device communication does not pass through the cloud and does not require Hub. Applications that use online weather, AI, or other network services may still need internet access, accounts, or API keys for those services.

Step 1: Prepare Your Device

  1. Confirm that your device is NOTE4 and runs firmware 3.7.2 or later.
  2. If an upgrade is needed, open Zectrix Cloud in Chrome or Edge, select “Local Upgrade,” and connect the device with a USB data cable. Follow the official firmware guide to select firmware for your device. Preserve important settings and data before upgrading.
  3. Set up the device's Wi-Fi and ensure that your computer and NOTE4 can reach each other on the local network.
  4. Enable “Keep Wi-Fi on in standby” under Settings → Network Sync. Maintaining connectivity increases power use, so check the battery during extended use. These labels correspond to 「设置 → 网络同步 → 待机保持 Wi-Fi」 on a Chinese-language device.
  5. Find the device's local IP address, for example in your router's connected-device list. The examples below use 192.168.1.100; replace it with your device's address.
  6. Close any other local application connected to the same device. Only one application can manage a device at a time.

Step 2: Choose an Application or Build Your Own

Use a Community Application

Browse local applications in the Developer Community and follow each project's installation or build instructions. Platform requirements, dependencies, and integration methods vary. Available source code does not necessarily mean an installable application is available.

If a project requires SDK integration, verify the minimal image-push workflow below before adding application logic. The standalone SDK does not include an app store, plugin loader, or desktop installer.

Develop Your Own Application or Use an AI Agent

The public SDK provides Rust source code, examples for images, status, buttons, recording, and playback, plus protocol documentation. Start with a single image, then extend it into a weather dashboard, photo album, or interactive application.

Step 3: Push Your First Image

These steps are for developers building from source. Install Rust stable, a platform C/C++ compiler, and CMake. On macOS, use Xcode Command Line Tools; on Windows, use Rust MSVC and Visual Studio C++ Build Tools; on Linux, install the appropriate build tools. The SDK repository records validation on Apple Silicon macOS; other platforms require build verification.

git clone https://github.com/itopinion/zectrix-local-push-sdk.git
cd zectrix-local-push-sdk
cargo test --locked
cargo check --locked --examples

The first build needs internet access to download dependencies. Save a 400 × 300 PNG image as card.png in the repository directory, then run:

cargo run --locked --example show -- 192.168.1.100 card.png mono

Replace the IP address with your device's address. mono selects monochrome; use gray4 or gray16 for 4-level or 16-level grayscale. Start with monochrome to confirm connectivity, then inspect grayscale results.

The SDK handles image conversion and transmission. Supply the original PNG without applying dithering beforehand, so the image is not dithered twice. Convert JPEG or SVG files to PNG in your application first.

How to confirm success: A successful show() call means the device has reported that display refresh is complete, rather than just that data was sent. Inspect the physical screen to confirm text size, layout, and grayscale quality. System notifications may temporarily cover part of the image.

To query device status, run this separate example:

cargo run --locked --example status -- 192.168.1.100

Run these standalone examples one at a time so they do not compete for the device. If an older Opus build script causes a CMake compatibility error, follow the SDK README and set CMAKE_POLICY_VERSION_MINIMUM=3.5 before retrying.

Buttons, Recording, and Disconnecting

Applications can receive short and long presses of Up and Down, and short presses of Confirm. The application defines what these events do. Button behavior during a local connection should not be assumed to match the regular Clock or Tasks pages.

Holding Confirm until the recording threshold displays a listening prompt; recording starts after the notification sound and ends when you release the button. The SDK cannot remotely activate the microphone. Receiving audio does not automatically produce text; your application needs speech recognition for that.

The entire 400 × 300 canvas is available to your application, with no permanently reserved area at the top. Recording prompts and task notifications temporarily overlay the screen; the application image returns afterward.

Before closing or switching applications, disconnect the original program. Developers should call close() during normal shutdown. After a connection ends, the application must explicitly establish a new connection; the SDK does not automatically take control again in the background.

Troubleshooting

Symptom What to check
Device not found or connection timeout Confirm that the device is online, standby Wi-Fi is enabled, and the IP is correct. Check whether guest-network isolation or a firewall blocks local communication.
Busy Check whether another program manages the device. Recording, playback, or image tasks can also make it busy; let the current operation finish before deciding to retry.
Protocol or palette compatibility error Confirm that NOTE4 runs firmware 3.7.2 or later, then check the SDK documentation and error details for the API in use.
Wrong proportions or text too small Design for 400 × 300 with clearly readable text. Other image sizes are scaled proportionally and centered.
Updates stop after the computer sleeps or the application closes Continuous updates require the host application and network connection. Reconnect after the host resumes.
ResultUnknown The operation may have run, but its result could not be confirmed. Check the device; do not automatically resubmit it as a new image or playback request.
Audio is received but no text or AI reply appears The SDK handles audio transport. The application must supply speech recognition, TTS, and model integration.

A Development Prompt for Your AI Agent

Give the following prompt to your AI coding assistant along with your application requirements:

Build a local NOTE4 application using https://github.com/itopinion/zectrix-local-push-sdk. First read the latest README and docs/API.md, confirm my device model, and check that its firmware is 3.7.2 or later. Do not upgrade firmware automatically. Connect only to the device address I specify. Generate 400×300 PNG images and implement a single monochrome image push before adding application features. Maintain one device connection, continuously consume button and recording events, and call close during normal shutdown. Do not treat transmission completion as display completion, and do not automatically resubmit ResultUnknown operations as new requests. Complete local builds and tests first, then report results based on the device's display-completion acknowledgment and identify anything not yet tested on hardware.

Developer Resources

Updated October 27, 2026. Local push supports NOTE4 firmware 3.7.2 and later. Refer to the SDK documentation for individual API details and changes.