ProductsSolutionsDocsVideosDownloadsCustomAbout
中文 Inquire
Home / Docs Center / Pet Feeder (ODM Case) / Detailed App Feature Design Doc

Detailed App Feature Design Doc

Pet Feeder (ODM Case) · Design Docs

XSTRIVE Smart Pet Feeder App

Detailed Function Design Document

Document Version: v2.1
Last Updated: 2026-04-23
Product Name: XSTRIVE Smart Pet Feeder
App Version: v1.0.0

Table of Contents

  1. Document Description
  2. Role Description and Abbreviations
  3. Data Storage Specification
  4. Function Module Overview
  5. Module 1: Authentication and Account
  6. Module 2: Home Page and Device Overview
  7. Module 3: Device Details and Real-Time Monitoring
  8. Module 4: Album (Capture and Recording)
  9. Module 5: Scheduled Feeding Plan
  10. Module 6: Pet Management
  11. Module 7: Device Settings
  12. Module 8: Family Management
  13. Module 9: Message Center
  14. Module 10: Device Network Configuration and Binding
  15. Module 11: Mine (Personal Center)

1. Document Description

1.1 Purpose

This document is the detailed functional design specification for the XSTRIVE Smart Pet Feeder App. It aims to clarify the specific responsibilities, data flow and status management of the App side, server side and device side at each function point, and to describe the functions with reference to the specific page screenshots in the HTML design draft, providing the development team with a complete and executable functional specification reference.

1.2 Scope

  • Development team: three-party collaborative development of the App side (iOS/Android), server side and device side

1.3 How to read this document

  • Each functional module is covered from the App side, the server side and the device side, one section per feature
  • Some modules include a design draft screenshot index, showing where that feature sits in the HTML design draft
  • Symbol legend:
  • 🟢 = This end needs to handle it
  • ⚪ = This end does not participate
  • ⭐ = Key / critical logic

1.4 About the design draft screenshot index

Every module heading in this document is followed by a design draft page reference.

Developers and testers can open the HTML file, jump to that page and look at the visual design draft of the module.

2. Roles and abbreviations

2.1 System roles

Role Description Design reference
Administrator Family founders with full authority to manage equipment, members and feeding schemes, and can delete/edit all plans Home management page (module 8)
Members Invitees to a family account to see the state of the equipment, triggers the manual feeding, looks at messages, cannot edit others' plans First page equipment card (module II)
Equipment Think fast about pet feeder hardware terminal, connect to App by WiFi/Bluetooth Device Details Page (module III)

2.2 Device model specifications

Item Specifications
Device Model Not available yet
Device Name Format XSW-model-{4 random letters} (for example XSW-PF200-AB12)
Firmware naming xsw-pf200-v{x.y.z}.bin
Support System iOS 12.0+ / Android 8.0+

2.3 Device status definitions

Status Description Display text Design mockup style
online Equipment is connected and functioning 🟢 Normal/ 🟢 Online First page card corner green
offline Device offline, cannot connect 🔴 Offline First page card corner mark gray
feeding Dispensing food ⏳ Dispensing First Page Card Load Animation
error Device error (food jam, communication failure, etc.) ❌ Error First page card red alarm

2.4 Abbreviations

Abbreviation Full name Description
BLE Bluetooth Low Energy Bluetooth, low power, for equipment networking
MQTT Message Queuing Telemetry Transport IoT messaging protocol
OSS Object Storage Service Object storage service (Alibaba Cloud / Tencent Cloud)
CDN Content Delivery Network Content distribution network
OTA Over-The-Air Over-the-air firmware update
RTC Real-Time Clock Real time clock, local timer for devices
RTMP Real-Time Messaging Protocol Real-time message transfer protocol (equipment video feed)
HLS HTTP Live Streaming HTTP Live Stream (App Pull)
RTSP Real Time Streaming Protocol Real-time streaming protocol (LAN direct pull)
JPEG JPEG Image compression format
AAC Advanced Audio Coding Audio encoding format
ACK Acknowledgement Confirm response
JWT JSON Web Token User identity token
Redis Redis In-memory database (verification codes / sessions)

3. Data storage specification

3.1 User data storage

Photo storage

Item Specifications Corresponding design element
Single Picture Size ~200KB (JPEG compression, 1280×960, quality 70%) Album Page Grid Presentation (module IV)
Color format JPEG (RGB) —
Photo ceiling per user 50 photos Album page "8/50 saved" counter
Retention period 7 days (automatic cleanup: the server deletes expired items and the app clears its local cache) —
Storage location Server-side object storage (OSS) + CDN acceleration —
Deletion policy A scheduled background job (daily at 03:00 UTC+8) deletes records older than 7 days by creation time —
Local Cache The app does not persist photos locally; it only caches thumbnails (cached on first view, 20 MB cap) Album page picture placeholder

Video storage

Item Specifications Corresponding design element
Single-part video duration At most 30 seconds (truncated automatically beyond 30 seconds) Device detailed page video button (hold UI hint)
One-part video size ~5 MB (H.264, 640×480, 15 fps, ~1.5 Mbps) —
Video Format MP4 (H.264 video / AAC audio) —
Video ceiling per user 5 segments Album page "2/5 saved" counter
Retention period 3 days (automatic cleanup: the server deletes expired items and the app clears its local cache) —
Storage location Server-side object storage (OSS) —
Deletion policy A scheduled background job (daily at 04:00 UTC+8) deletes records older than 3 days by creation time —

Device status data structure

// Device status reported in real time (MQTT, HTTP polling as a fallback)
{
  "device_id": "PF200-ABC123",
  "sn": "XSW20260408PF200",
  "model": "PF200",
  "firmware_version": "v2.1.0",
  "online": true,
  "power_mode": "plug",
  "battery_level": 100,
  "food_level": 75,
  "food_weight_g": 750,
  "last_feeding_time": "2026-04-23T10:30:00+08:00",
  "today_feeding_count": 3,
  "today_feeding_total_g": 85,
  "total_feeding_count": 128,
  "total_feeding_g": 3840,
  "runtime_hours": 12,
  "network_rssi": -45,
  "error_code": 0,
  "error_message": "",
  "camera_stream_url": "rtmp://media.xswei.com/live/PF200-ABC123",
  "camera_status": "active",
  "microphone_status": "active",
  "speaker_status": "active",
  "timestamp": "2026-04-23T11:55:00+08:00"
}

Device error code definitions:

error_code Description Severity User prompt
0 No error — —
101 Hopper not installed Medium Please install the hopper correctly
102 Hopper not closed Medium Please close the hopper lid
201 Food jam detected High Food dispensing error; please check and clear the outlet
202 Motor overload High Motor error; please contact support
301 Camera failure Low The cameras are abnormal, but the feeding is normal
302 Microphone failure Low Voice function abnormal
303 Speaker failure Low Voice playing anomaly
401 WiFi Connection Disconnected Medium Please check the network connection
402 Cloud connection disconnected Medium Please check the network connection
403 OTA update failed Medium Firmware update failed; please try again
501 Battery depleted High Device battery is empty; please charge

Feed record storage

Field Type Description
id UUID Unique identifier for record
device_id String Device ID
user_id String Operating user ID
pet_id String Linked pet ID (optional; null means no linked pet)
family_id String Family ID
feed_type Enum manual (manual feeding) / scheduled (scheduled feeding)
feed_plan_id UUID Linked feeding plan ID (set for scheduled feedings)
feed_amount_g Integer Amount dispensed (g); the actual amount (may differ from the plan, for example when food jams)
feed_time DateTime Feed time
result Enum success / fail
fail_reason String Failure reason (set when result=fail)
actual_weight_g Integer Weight measured by the load cell (hopper weight lost after dispensing)
food_level_after Integer Remaining food percentage after feeding
  • Length of storage: feeding records are kept permanently and can be exported per month or per device
  • : feeding records are kept permanently and can be exported per month or per device: a single app query returns at most 100 records, with cursor paging
  • : a single app query returns at most 100 records, with cursor paging: first page of Statistics Today module showing the number and total grams of today's feeding; device details page showing today/week/month statistics

Household data storage

Field Description Design reference
family_id Unique family ID —
family_name Family name (for example, "Bella's Family") Family switch dropdown at the top of the home page
owner_id Creator (admin) user ID List of family management members
created_at Creation time —
address Family address (optional) —
timezone Time zone (default Asia/Shanghai) —
member_count Number of members (including the admin) Mine page "1 family" counter

4. Functional module overview

# App Side App Server Device priority The script corresponds to the page
1 ✅ ✅ ✅ ⚪ P0 Login/registration page
2 ✅ ✅ ✅ ⚪ P0 Home Page
3 ✅ ✅ ✅ ✅ P0 Device Details Page
4 ✅ ✅ ✅ ✅ P1 Album Page
5 ✅ ✅ ✅ ✅ P0 Feeding program page
6 ✅ ✅ ✅ ⚪ P1 Pet Page
7 ✅ ✅ ✅ ✅ P1 Device Settings Page
8 ✅ ✅ ✅ ⚪ P1 Family management page
9 ✅ ✅ ✅ ⚪ P1 Chile
10 ✅ ✅ ✅ ✅ P0 Add Device Page
11 ✅ ✅ ✅ ⚪ P2 My Page

5. Module I: Authentication and accounts

Corresponding page: sign-in / sign-up page (auth-page)
Design mockup description: the page uses a full-screen gradient background (deep teal → teal → light teal) with the logo and app name centred at the top, and a white rounded card below holding the sign-in and sign-up forms. The main tabs switch between Sign in and Sign up; the sub-tabs switch between code sign-in and password sign-in.

!image-20260423163202366

5.1 Module overview

Supports mobile phone number + authentication code login, mobile number + password login, and new user registration process. The account system is a family-sharing system, with the same mobile phone number to join multiple families.

5.2 Feature 1: sign-in by verification code

Feature description: the user enters a phone number, receives an SMS verification code and signs in.

Corresponding design elements (HTML lines 530~600):
- Phone number input box (with the +86 prefix)
- Get verification code button (shows a 60-second countdown after tapping)
- 6-digit verification code input box
- Login button

Dimension Description
App 🟢 Enter mobile number (11 digits, mainland China format, shown with a +86 prefix) → request a verification code → enter the 6-digit code → call the sign-in API → store the JWT token → go to the home screen
Server 🟢 Validate the phone number format → generate a 6-digit numeric code (single use) → store it in Redis (key=sms:login:{phone}, TTL=300s) → call the SMS gateway to send it → verify the user input → find or create the user record → issue a JWT token
Device No participation

Data specifications:

Item Specifications
Verification code length 6 digits
Code validity 5 minutes (300 seconds)
Send rate per phone number At most once every 60 seconds
Retry limit 5 consecutive errors lock the account for 15 minutes
While locked Returns the error ERR_CODE_LOCKED and sends no SMS
JWT access_token lifetime 7 days
JWT refresh_token lifetime 30 days

5.3 Feature 2: password sign-in

Feature description: the user enters a phone number and password to sign in.

Corresponding design elements

  • Phone number input box
  • Password input box (with show/hide toggle icon)
  • Remember account checkbox
  • Forgot password text link
  • Login button
Dimension Description
App 🟢 Enter the phone number and password → tick "Remember account" (the phone number is stored locally) → call the sign-in API → store the token → go to the home screen
Server 🟢 Verify that the account exists → verify the password (bcrypt comparison) → issue a JWT
Device No participation

Password rules: 6–20 characters; letters, digits and symbols are all allowed, and the password must contain both letters and digits.

5.4 Feature 3: registration

Feature description: a new user registers with a phone number, and the first family is created automatically once registration succeeds.

Corresponding design elements:

  • Phone number input box (+86 prefix)
  • Get verification code button + verification code input box
  • Set password input box (with show/hide toggle)
  • Confirm password input box
  • User agreement checkbox (links to the agreement page)
  • Register button
Dimension Description
App 🟢 Enter mobile number → get verification code → set a password (6–20 characters, with letters and digits) → confirm the password → accept the agreement → submit registration
Server 🟢 Verify that the phone number is unique (not yet registered) → create the user record → issue a JWT → automatically create the first family (default name "{nickname}'s Family", editable)
Device No participation

Data specifications:

Item Specifications
Phone number 11-digit mainland China mobile number (regex /^1[3-9]\d{9}$/)
Password 6–20 characters, must contain both letters and digits
Confirm password Must match the password exactly
Verification code 6 digits, valid for 5 minutes; the same phone number can register once every 30 days
Nickname Optional, 2–20 characters; defaults to "User{last 4 digits of the phone number}" at registration

Automatic behaviour after registration:
1. A JWT token is issued (the user lands on the home screen without signing in again)
2. A family is created automatically (named "{nickname}'s Family" by default)
3. The registration source is recorded (iOS / Android / app version)

5.5 Feature 4: account security

Feature description: change the password and bind the phone number.

Corresponding design: "My" page → Settings → account security settings page

Dimension Description
App 🟢 Show the current binding (phone number masked as 138****1234) → changing the password requires the old password
Server 🟢 Change the password (verify the old password, then re-hash with bcrypt)
Device No participation

6. Module II: Home page and device overview

Corresponding page: home page (home-page)
Design mockup description Design mockup description

!image-20260423163501832

6.1 Module overview

The first page, after the user opens the App, presents an overview of the status of the bound equipment, the fast-track entry (manual feeding, scheduled entry), statistics on the number of family members/pets, and the display of pet cards.

6.2 Feature 1: device cards on the home screen

Feature description: shows the device name, a live thumbnail (placeholder), the online status and today's feeding statistics.

Corresponding design elements:

  • Device card: thumbnail area (rounded rectangle placeholder) + device name + status corner mark (online/offline) + today's statistics row (🍚 Today's feeding ×3 times, 85g in total) + bottom shortcut operation row
  • Shortcut operation row: 📷 Record ⏰ Plan ⚙️ Settings
  • Shortcut line: 📷 Video ⏰ Plan ⚙️ Settings
Dimension Description
App 🟢 On page load, request the device list API → show the device cards (name, status, remaining food %, feeds today) → tapping a card opens the device details → the quick-action icons each open the corresponding sub-page
Server : the device status is cached for 30 seconds (Redis) to reduce the MQTT reporting pressure on the device side Status Cache Policy: cache device status for 30 seconds (Redis) to reduce MQTT reporting pressure from devices
Device No participation

Device card data structure:

Field Type Description
device_id String Unique device ID
device_name String User Set Device Name
online Boolean Whether the device is online
food_level Integer Remaining food percentage (0–100)
today_feeding_count Integer Number of feedings today
today_feeding_total_g Integer Total feeding (grams) today
thumbnail_url String Device monitoring thumbnail URL (update frame)
camera_status String active = OK / offline = error / disabled = turned off

6.3 Feature 2: manual feeding (quick action)

Feature description: a Manual feed button below the device card on the home screen dispenses food with a single tap.

Corresponding design elements: Device Detailed Page Device Bottom Right Point "Hand Feed" button (theme colour button, click to load)

Dimension Description
App 🟢 Tap "Manual feed" → show a loading state (button greyed out with a spinner) → call the API → wait for the device (up to 5 seconds) → show success or failure in a toast → update today's statistics
Server 🟢 Receive the request → verify the user's permission on the device (family membership lookup) → verify that the device is online → forward the MQTT message to the device → wait for the device ACK (5-second timeout) → record the feeding log
Device 🟢 Receive the MQTT message (topic=device/{device_id}/feed) → run the dispensing action (the stepper motor turns a set angle) → confirm the amount with the load cell → report the dispensing result

Manual feeding specifications:

Item Specifications
Click the button once to dispense one portion Hit the button once. Give me a piece of food
The "default food amount" in the device settings (range 5-200g, can be modified on the device settings page) The "default portion size" in device settings (range 5–200 g, adjustable on the device settings page)
When the remaining food in the container < the default food amount, a confirmation prompt "Insufficient food remaining, continue?" pops up when & lt; defaults, eject confirmation hints "weak, do we continue?"
The interval between two manual feedings on the same device must be ≥ 1 minute (to prevent accidental touches) Two manual feeding breaks for the same device
All family members can trigger manual feeding Family members can trigger manual feeding. Eat

6.4 Feature 3: switching family

Feature description: one account can belong to several families. The top of the home screen shows the current family; tap it to open the switch panel.

Corresponding design elements: the "🏠 Bella's Family ▾" control on the left of the navigation bar (tap it to open a dropdown listing every family, with the current one ticked)

Dimension Description
App 🟢 Tap the family name to open the switch panel → show the family list (the current family is ticked) → after selection, save it locally (the default family next time) and request the new family's device list → refresh the home screen
Server 🟢 GET /api/v1/families (returns every family the user belongs to, with the device count for each) → on switch, GET /api/v1/devices?family_id=xxx
Device No participation

7. Module III: Device details and real-time monitoring

Corresponding page: device details page (live-page / device-detail-page)
Design mockup description: the top of the screen is the live video area (black background, 16:9). A back button sits in the top-left corner, the device name label is overlaid top-left, and a red LIVE dot plus the current time are overlaid top-right. Below the video is the control bar: snapshot, record (fullscreen), intercom and fullscreen buttons. Then a food-level progress ring (large donut), today's feeding statistics card, and a row of quick actions (device settings, feeding schedule, share, more).

!image-20260423163640968

7.1 Module overview

The device details page is the Apple core interactive page, which contains real-time video surveillance footage, a control bar (capture/video/talk/full screen), surplus food/feeding statistics, and a fast-tracking device entry.

7.2 Feature 1: live monitoring stream

Feature description: shows the device camera live feed (RTMP ingest + HLS playback), with a LIVE badge and the current time in the top-left corner, and supports switching between streams.

Corresponding design elements:

  • Top left: "📹 Device Name" white semi-transparent label
  • Top right: "🔴 LIVE" red dot label + time display "14:32:05"
  • While the video is loading: a loading animation (rotating circle) is displayed in the center
  • When the video is disconnected: a disconnection icon + "Video connection interrupted, click to retry" is displayed
  • Audio: muted by default, stays muted before intercom is enabled
  • Audio: Default Mute, keep still before opening the intercom
Dimension Description
App 🟢 Use a video player component (iOS: AVPlayer / Android: ExoPlayer) → connect to the HLS URL (.m3u8) → play live video → audio muted by default → reconnect automatically if the stream drops (3 retries, 5 seconds apart, then show a manual retry button)
Server 🟢 Provide an RTMP ingest address (the device pushes to the media server) → transcode to HLS (.m3u8 + .ts segments, 4 seconds each) → stream URL with a temporary token (valid 10 minutes; the app refreshes it every 8 minutes)
Device 🟢 Camera captures video → H.264 encoding → push to the server media server over RTMP (rtmp://media.xswei.com/live/{device_id}) → adaptive bitrate on the device (256 kbps–2 Mbps)

⭐ Camera channels and multi-stream support:

Item Specifications
Camera channels Single channel (built-in camera, no external expansion)
Supported streams The device outputs two streams at the same time: main stream (high definition, 1920×1080) and sub stream (standard definition, 640×480)
Default stream Sub stream (SD, saves bandwidth and device resources)
App stream switching Select "SD 640×480" (default) or "HD 1920×1080" on the device settings page; the server then switches the transcoding parameters
Ingest protocol RTMP (device → server-side media server)
App pull protocol HLS (.m3u8 + .ts segments, 4 seconds each, 8 segments cached)
End-to-end latency ≤3 s (SD) / ≤4 s (HD)

Video stream specifications:

Item Specification (SD) Specification (HD) Notes
Codec H.264 H.264 —
Resolution 640×480 1920×1080 Toggle in Device Settings
Frame rate 15fps 15fps —
Bitrate 512 kbps (adaptive 256k–1M) 1 Mbps (adaptive 512k–2M) Automatically lowers the bitrate on a poor network
Audio AAC 32 kbps mono AAC 32 kbps mono —
HLS segment length 4 seconds 4 seconds —
Offline detection After the device goes offline, the app waits at most 30 seconds before showing the offline state — —

Stream address refresh mechanism:

Step Operation
1 First load of the video page in the app → GET /api/v1/devices/{id}/stream-url
2 Server response: {hls_url: "https://.../live.m3u8?token=xxx", expires_at: "+10min"}
3 The app plays the HLS stream (AVPlayer / ExoPlayer)
4 A timer refreshes the token every 8 minutes (or 2 minutes before expires_at)
5 GET /api/v1/devices/{id}/stream-url (refresh) → the player switches to the new address (seamless, without interrupting playback)

7.3 Feature 2: taking a snapshot

Feature description: tapping Snapshot over the live view captures the current frame as a JPEG image, uploads it to the server and saves it to the album.

Corresponding design elements:

  • After clicking: the screen flashes white once (simulating a shutter effect) + a Toast at the top right "✅ Capture successful, saved to album"
  • Capture count statistics +1 (e.g. "9/50 photos stored")
  • Capture Number + 1 (e. g. "[1 / 2] Chang")

Corresponding design elements (HTML lines 1325–1340):
- The "Snapshot and recording" entry card at the bottom of the device details page, showing thumbnail previews plus a "12 photos · 3 videos" count

Dimension Description
App 🟢 Tap capture → decode the current frame from the live stream (AVCaptureVideoDataOutput / VideoFrame) → JPEG compression (1280×960, quality 70%, ~200 KB) → show a local preview (optional delete) → upload to the server → save to the album → update the local counter
Server 🟢 Accept the image upload (multipart/form-data, ≤500 KB each) → store in OSS → generate a CDN URL → write to the database (device_id, user_id, family_id, timestamp) → check whether the user has reached the 50-photo limit → if so, delete the oldest photo
Device ⚪ Not involved (the app grabs the frame from the video stream itself)

⭐ Snapshot local cache policy:

Phase Behaviour
Immediately capture the video frame (< 100ms response), display the shutter effect (white flash for 100ms) Capture a video frame immediately (< 100 ms response) and show a shutter effect (100 ms white flash)
App local compression (no server request, < 500ms) App-side local compression (no server request, < 500 ms)
Display the thumbnail preview (automatically disappears after 1 second, or the user manually deletes it) Show thumbnail preview(s) automatically disappear after 1 seconds, or user manually delete)
Background upload (does not block the user from continuing operations); if the upload fails, it is kept locally for 3 days and retried Background upload (without blocking the user); if an upload fails, the file is kept locally for 3 days and retried
Upload immediately after capture; delete the local temporary file after a successful upload; if the upload fails, keep it and retry up to 3 times (intervals of 30 seconds / 1 minute / 5 minutes) Upload immediately after capture; on success delete the local temporary file, on failure keep it and retry up to 3 times (after 30 seconds, 1 minute and 5 minutes)

Upload immediately after capture; on success delete the local temporary file, on failure keep it and retry up to 3 times (after 30 seconds, 1 minute and 5 minutes):

Item Specifications
Image format JPEG (RGB)
Resolution 1280×960 (fixed, independent of the stream resolution)
Compression quality 70%
File size ~200KB
Limit per user 50 photos (the oldest is deleted automatically when exceeded, with no prompt)
Retention period 7 days (cleaned up by a background job daily at 03:00 UTC+8)
Upload method HTTPS POST multipart/form-data
Upload timeout 10 seconds; on timeout, show "Upload failed, tap to retry"
Shutter response latency < 100 ms (from the tap to the white flash)
Image source The decoded frame of the current video player, not a device-side screenshot

7.4 Feature 3: recording

Feature description: hold Record to start and release to stop; the result is an MP4 clip of up to 30 seconds, uploaded to the server and saved to the album.

Corresponding design elements:

  • When pressed, the button turns red + the REC indicator is displayed + a recording duration countdown "⏺ REC 00:24 / 00:30"
  • Text prompt below "Press and hold to record, up to 30 seconds"
  • Next text hint "Long by video, maximum by 0"
Dimension Description
App 🟢 Hold the record button → request microphone permission (asking first if not granted) → start recording a local temporary video file (H.264, 640×480, 15 fps) → show a red REC dot and a countdown at the top of the screen → release (or reach 30 seconds) to stop → compress the video → upload to the server → save to the album → show a toast
Server 🟢 Receive video upload (multipart/10MB, ≤) → Store to OSS → Write to database → Checks if the number of videos reaches the maximum of 5 → Overlimits delete the earliest 1
Device ⚪ No participation (Video completed locally at App end, using App's own camera and microphone for surveillance)

⭐ Note on video sources:

Item Description
Captured from the device monitoring video stream (the App decodes the H.264 frames and re-encodes them into MP4) Intercept device monitor video stream (App end decode H. 264 frame and recode to MP4)
App-side microphone collection (ambient sound, i.e. the sound of pets and the surrounding environment) App End mic harvesting (environmental sound, i.e. pet and surrounding environment)
The sound in the recording is collected by the App-side device microphone, not the sound emitted from the device-side speaker The sound in the video is the sound of the app device microphone, not the sound from the device speaker
Fixed to the main stream of the current device (the device firmware push channel) for recording; cannot be switched to another channel Recording of the fixed use of the main stream of the current device (the equipment solids push the flow route) without switching to other channels

⭐ Video upload path classification policy:

Phase Storage location Description
App local temporary file (.mp4) Written to the App temporary directory (e.g. tmp/) to prevent loss on crash Writing App temporary directory (e. g. tmp/), protection against crash loss
App local cache (.mp4, kept until the upload succeeds) A local backup is kept during the upload Keep backup locally during upload
Server-side OSS (temporary directory) multipart segmented upload, supports resumable upload multipart part upload in support of breakpoints pass
Server-side OSS (official directory) A video thumbnail is generated at the same time (FFmpeg extracts the frame at the 1st second) Also generate video thumbnails (FFmpeg extracts the second frame)
CDN accelerated distribution (thumbnail + video stream) The CDN URL is delivered to the App CDN URL down to App

Video resumable upload mechanism:

Scenario Treatment
Record the uploaded segment index and continue from the breakpoint after the network is restored (HTTP Range) Record uploaded fraction index, continued from breakpoint next time the network recovers (HTTP Range)
When the App is reopened, detect the locally incomplete files and automatically resume the upload Reopen App to detect local files that are not uploaded and continue automatically
Keep the local file and prompt the user "Video upload failed, please check the network and retry" Keep local files and alert users to "View upload failed. Check the network and try again"
30 seconds → 1 minute → 5 minutes One minute. One minute

Recording specifications:

Item Specifications
Video Format MP4 (H.264 video / AAC audio)
Resolution 640×480 (fixed, matching standard-definition streaming)
Frame rate 15fps
Bitrate ~1.5 Mbps (encoded live while recording)
Maximum length 30 seconds (truncated automatically beyond that)
Size per clip ~5MB
Limit per user 5 clips (the oldest is deleted automatically when exceeded, with no prompt)
Retention period 3 days (cleaned up by a background job daily at 04:00 UTC+8)
Upload method HTTPS POST multipart/form-data (large files chunked, 1 MB per chunk)
Upload timeout 60 seconds (single chunk); no overall limit (it runs in the background)
Thumbnail generation The server uses FFmpeg to grab a frame at the 1st second (JPEG, 320×240)
Local temporary copy Kept locally until the upload succeeds, then the temporary file is deleted

7.5 Feature 4: two-way voice intercom

Feature description: tapping Intercom opens the intercom panel; hold to speak through the device speaker while the device audio (pet sounds and so on) is streamed to the app.

Corresponding design elements:

  • After clicking: the intercom panel slides out from the bottom (semi-transparent mask + circular speak button)
  • The speak button is centered, with the text "Press and hold to speak, release to end" above it
  • While speaking, the button displays a volume waveform animation
  • When intercom is active, a "🎤 Intercom in progress" green label is displayed at the top left of the video image on the device details page
  • When speaking about activation, the top left corner of the device details page displays the green label "P"
Dimension Description
App : press and hold the speak button → the microphone collects audio (Opus encoding, 16kHz mono) → send it to the server in real time through WebSocket → the server forwards it to the device; device→App direction: receive the device-side audio stream (WebSocket) → Opus decoding → play through the speaker/headphones Device & App orientation WebSocket decodes → loudspeakers/headphones playing
Server (use and discard) Do Not Store (use or abandonment)
Device 🟢 Receive the audio stream (Opus packets over WebSocket) → decode Opus → play through the speaker (volume adjustable) → capture audio with the device microphone (16 kHz mono) → encode Opus → report to the server over WebSocket

Intercom specifications:

Item Specifications
Codec Opus (app ↔ server) / G.711 μ-law (fallback)
Sample rate 16kHz
Channels Mono
Bitrate 32 kbps (Opus)
Transport WebSocket (full-duplex, real time)
Latency requirement ≤500 ms (end to end)
Intercom timeout Up to 60 seconds per press (so a forgotten button cannot hold the channel)
Device speaker Can be disabled in device settings (speaker_status=disabled)
Device microphone Can be disabled in device settings (microphone_status=disabled)

⭐ Full duplex vs half duplex (only one party can speak at a time) to avoid echo and interference. When the device detects that the ambient volume is too high (pet calls, etc.), it can automatically reduce the uplink audio bitrate.Half-difference (Only one side at the same time) avoid echoes and interference. When the end of the device detects an excessive environmental volume (pets barking, etc.), it automatically reduces the upper audio frequency.

7.6 Feature 5: fullscreen mode

Feature description: tapping Fullscreen plays the video full screen in landscape with the control bar hidden; tap the screen to return to portrait.

Corresponding design elements: The fourth icon button of the Monitor Control Bar, full screen (round, white side), rotates the screen behind the click, the video is full of screens and the top status bar is hidden.

Dimension Description
App 🟢 Rotate the screen to landscape → hide the top navigation bar and the bottom tab bar → video fills the screen → the control bar shrinks to a floating overlay in the bottom-right corner (snapshot / record icons) → tap anywhere to bring the controls back; they hide again after 3 seconds of inactivity
Server No participation
Device No participation

7.7 Feature 6: remaining food and today's feeding statistics

Corresponding design elements:

  • Text below "Food container remaining / about 750g" (displaying the actual weight in grams)
  • Today's statistics card: today's feeding "3 times" + total "85g"
  • Today's statistics card: fed today "3 times" plus a total of "85 g"
Dimension Description
App 🟢 when loading the page to get food level from device status data and food weight g → ring progress proportionally displays orange warning when below 20% + reminder to pop up "unsufficient food" on top of the card
Server 🟢 equipment status reported with food level (percentage) and food water g (actual grams)
Device →MQTT reports food level and food weight g

8. Module IV: Album (snapshots and recordings)

Corresponding page: Album page (album-page / gallery-page)
Design mockup description: Top navigation bar "📷 Album" + "Filter" icon at the top right. Filter tabs: "All / Photos / Videos". The main body uses a grid layout (3 columns); photos show thumbnails (rounded corners) and video thumbnails are overlaid with a play icon (▶) plus a duration label (e.g. "0:25"). Storage statistics bar: "10/50 photos stored · 2/5 videos".

!image-20260423164016822

8.1 Module overview

The album page centrally manages the photos captured and videos recorded by users on the device details page. It provides filtering, preview and deletion functions, and displays storage usage statistics.

8.2 Feature 1: album list

Feature description: Display photo and video thumbnails in a grid, supporting three filters: "All/Photos/Videos".

Corresponding design elements:

  • Filter tab bar (All/Photos/Videos)
  • Storage statistics bar (displays "10/50 photos stored · 2/5 videos"; this text element does not exist in the HTML but the layout is retained)
  • Grid area (3 columns, 4px spacing, photos and videos displayed together)
  • Video thumbnails overlaid with a play icon (▶) + duration label (e.g. "0:25")
  • Photo thumbnails overlaid with the capture time (relative time, e.g. "3 minutes ago")

Corresponding design elements: The "Capture and Recording" entry card at the bottom of the device details page:

  • Left icon area (orange gradient background, photo icon) + title "Capture and Recording" + statistics text "12 photos · 3 videos"
  • Right thumbnail preview (3 small circular images)
  • Tap to jump to the album page
Dimension Description
App 🟢 Request the album list API (GET /api/v1/media?type=all/photo/video&page=1&limit=20) → grid display (3 columns) → video thumbnails overlaid with a play icon + duration → pull down to refresh, pull up to load more (20 items/page) → a skeleton screen is displayed on first load
Server 🟢 Query the album records of the current user (in reverse chronological order, filtered by media_type) → return paginated → for videos, additionally return a thumbnail URL (the server uses FFmpeg to extract a frame from the 1st second of the video as the thumbnail)
Device No participation

Data specifications:

Field Type Description
media_id UUID Unique identifier of the media record
media_type Enum photo / video
cdn_url String CDN access URL (original photo / video playback address)
thumbnail_url String Thumbnail URL (small photo image / first video frame in JPEG)
device_id String Source device ID
device_name String Source device name (name set by the user)
duration Integer Video duration (seconds; only has a value for the video type)
duration_label String Formatted duration label, e.g. "0:25"
created_at DateTime Creation time, ISO 8601
relative_time String Relative time description, e.g. "3 minutes ago", "Yesterday"
photo_limit Integer User photo limit (fixed at 50)
video_limit Integer User video limit (fixed at 5)
total_photo Integer Current number of photos
total_video Integer Current number of videos

8.3 Feature 2: photo preview and deletion

Feature description: Tap a photo to enter full-screen preview, swipe left/right to switch photos, and tap the delete button and confirm to delete.

Corresponding design elements (interactive elements are controlled by JS):

  • Full-screen preview (black background, image centered, semi-transparent information bar at the bottom)
  • Bottom information bar: device name "Xiaobei's Feeder" + capture time "April 23, 2026 14:30"
  • Delete icon at the top right (🗑 red)
  • Swipe left/right to switch photos
  • Bottom action bar: share button / delete button
Dimension Description
App 🟢 Tap a photo → full-screen preview → support switching by swiping left/right (horizontal scrolling, infinite loop) → tap the delete icon at the top right → confirmation dialog "Delete this photo? It cannot be recovered after deletion" → call the delete API → refresh the current list
Server 🟢 DELETE /api/v1/photos/{photo_id} → delete the OSS file (async task) → delete the database record → return success
Device No participation

8.4 Feature 3: video preview and deletion

Feature description: Tap a video thumbnail to call the system player for full-screen playback; tap the delete button and confirm to delete.

Corresponding design elements:

  • After tapping, play directly in full screen (calling the system player, or the App's embedded ExoPlayer/AVPlayer)
  • Playback screen: video image + progress bar + duration display + play/pause button
  • A delete icon (🗑) is displayed at the top right when paused
  • Deletion confirmation dialog "Delete this recording? It cannot be recovered after deletion"
Dimension Description
App 🟢 Tap a video → call the system player (AVPlayer / ExoPlayer) for full-screen playback → when playback finishes or delete is tapped → confirmation dialog → call the delete API → refresh the list
Server 🟢 DELETE /api/v1/videos/{video_id} → delete the OSS file (async) → delete the database record → return success
Device No participation

8.5 Feature 4: sharing

Feature description: Photos or videos can be shared to WeChat, WeChat Moments, QQ, etc.

Corresponding design elements: The "Share" button in the bottom action bar of the photo/video preview page

Dimension Description
App 🟢 Tap Share → bring up the system share panel (ShareSheet) → support sharing images (JPEG URL) or videos (local file path)
Server No participation

8.6 Storage specification summary (album module)

Media Type Format Resolution Single File Size User Limit Retention period Automatic Cleanup Time
Photo JPEG 1280×960 ~200KB 50 photos 7 days Daily 03:00 UTC+8
Videos MP4 (H.264) 640×480, 15fps ~5MB/clip 5 clips Day Daily 04:00 UTC+8

Silent handling when the storage limit is reached: After the limit is reached, the oldest records are automatically deleted. No dialog is shown to the user and the current operation flow is not interrupted.

9. Module V: Scheduled feeding plans

Corresponding page: Feeding plan page (feeding-plan-page)
Design mockup description: Top navigation bar "⏰ Feeding Plan" + "+" add button at the top right. The main body is the plan list. Each plan card shows: pet avatar (emoji) / default icon + pet name + feeding time (bold large text such as "08:00") + feeding portion "30g" + repeat cycle labels (Monday to Sunday icons, today is highlighted) + toggle button (ON/OFF). At the bottom there is a "+ Add Plan" floating button.

!image-20260423164207392

9.1 Module overview

Administrators can create, edit and delete scheduled feeding plans (supporting daily repeat / by workday / by specified weekday repeat). The device side automatically dispenses food according to the plan delivered by the server; the App does not need to be online.

9.2 Feature 1: plan list

Feature description: Display all feeding plans of the current device, showing time, portion, pet, repeat cycle and toggle status.

Corresponding design elements:

  • Plan card: pet icon + pet name + time "08:00" (bold) + portion "30g" + repeat cycle (small dots from Monday to Sunday, the current day is solid and highlighted) + toggle button
  • Empty list state: "No feeding plan yet" + icon + "Tap the button below to add"
  • Visible to administrators: edit (✏️) and delete (🗑) operation entries
  • Visible to members: only the list is displayed; editing is not possible
Dimension Description
App 🟢 Request the plan list API (GET /api/v1/feeding-plans?device_id=xxx) → list display (sorted by time) → edit/delete buttons are shown to administrators; members can only toggle plans
Server 🟢 Query the plan list associated with the device → return sorted by plan time → include user role information for the App to determine operation permissions
Device No participation

9.3 Feature 2: creating a plan

Feature description: The administrator fills in the feeding plan form, setting the time, pet, portion and repeat cycle.

Corresponding design elements (form page): Add plan page form:

  • Device selection (if the family has multiple devices, the current device is selected by default)
  • Pet selection (can be skipped, displayed as "No pet linked")
  • Feeding time picker (clock style, scroll wheel to select "08: 00")
  • Food portion picker (slider or numeric input, range 5-200g, step 5g, with scale displayed)
  • Repeat cycle selection (Monday to Sunday icon button group, tap to toggle the selected state)
  • Save button
Dimension Description
App 🟢 Fill in the form → validate required fields → submit POST /api/v1/feeding-plans → return to the list page after success
Server 🟢 Create the plan record → immediately push it to the device side via MQTT (stored locally on the device) → record the operation log
Device 🟢 Receive the plan MQTT message (topic=device/{device_id}/plan/update) → store it in local Flash → dispense food on schedule according to the plan (RTC wake-up)

New plan data specifications:

Item Specifications
Food portion range 5-200g, step 5g
Time selection 00:00-23:59, accurate to the minute
Repeat cycle Any combination from Monday to Sunday, at least 1 day must be selected
Common shortcuts "Every day" selects Monday to Sunday with one tap / "Workdays" selects Monday to Friday with one tap
Pet association Optional (not selecting = no pet linked)
Plan limit per device 20

9.4 Feature 3: editing or deleting a plan

Feature description: Administrators can edit any field of an existing plan; they can delete a plan (a second confirmation is required).

Corresponding design elements:

  • Edit: tap the plan card or the edit button → enter the edit form page (same content as creation, auto-filled)
  • Delete: tap the delete button → a confirmation box pops up "Delete the "08:00 · 30g" plan? It cannot be recovered after deletion"
Dimension Description
App 🟢 Edit: GET to fill the form → PUT /api/v1/feeding-plans/{id}; Delete: confirmation dialog → DELETE → refresh the list
Server 🟢 Update/delete the plan → immediately notify the device side via MQTT
Device 🟢 Receive MQTT → update/delete the corresponding plan in local Flash

9.5 Feature 4: plan switch (member permission)

Feature description: All family members (including ordinary members) can enable/disable a feeding plan.

Corresponding design elements (Toggle Switch on the right of each plan)

Dimension Description
App 🟢 Tap the toggle → PATCH /api/v1/feeding-plans/{id} {enabled: true/false} → update the local state → done if successful, roll back the toggle state if it fails
Server 🟢 Update the enabled field → notify the device side via MQTT
Device 🟢 Receive MQTT → update the enabled state of the local plan → when enabled=false, skip execution of that plan

⭐ Permission Rule: Only administrators can edit/delete plans. Ordinary members can only operate the toggle (enable/disable a plan) and cannot edit core fields such as time/portion.

9.6 Feature 5: scheduled execution on the device

Feature description: The device side automatically dispenses food according to the locally stored plan when the set time is reached.

Dimension Description
Server 🟢 Does not directly control the device; the device executes autonomously; the server records the execution result of each scheduled feeding (reported by the device)
Device 🟢 RTC timer monitoring (wakes up to check once per minute) → when the time is reached and today's repeat_days includes the current weekday → the stepper motor dispenses food → the weighing sensor confirms the dispensed amount → compares it with the planned amount (an error of ±10g is acceptable) → reports the execution result via MQTT

Offline handling:
- The device stores the complete plan list locally and the RTC still executes feeding according to the plan while offline
- After going back online, the device side immediately reports the feeding records from the offline period (topic=device/{device_id}/feed/batch-report)
- After receiving them, the server backfills the feeding records, and the user can view them in the App

Food jam handling:
- Weighing sensor detection: if the actual dispensed amount is < the planned amount − 10g after dispensing, it is judged as a food jam
- The device side automatically retries (up to 3 times, 10 seconds apart each time)
- If the retries still fail: report error_code=201, and the App pushes an alarm message "Abnormal food dispensing. Please check and clean the food outlet"

10. Module VI: Pet management

Corresponding page: Pet page (pet-page)
Design mockup description: Top navigation bar "🐾 My Pets" + "+" add button at the top right. The main body is a list of pet cards. Each card: pet avatar (large emoji or custom image, circular) + pet name (bold) + pet type/breed "Dog · Corgi" + age/gender tag + bottom action "🍚 Feeding Records" button. Empty list state: blank placeholder image + "No pets yet, tap to add" + add button.

!image-20260423164501579

10.1 Module overview

Manage the pet profiles in the family (avatar, name, type, breed, age, gender). Pets are linked to feeding plans, making it easy to record the pet corresponding to each feeding.

10.2 Feature 1: pet list

Feature description: Display all pet cards in the family (avatar, name, type/breed/age/gender).

Corresponding design elements:

  • Pet card: circular avatar (emoji or custom image) + pet name + type/breed line + age/gender tag
  • Card bottom: "🍚 Feeding Records" button
  • Shown to administrators: edit (✏️) and delete (🗑) operation entries
  • Shown to members: view only, cannot edit
Dimension Description
App 🟢 Request the pet list API (GET /api/v1/pets?family_id=xxx) → card display
Server 🟢 Query the pet list associated with the family, sorted by creation time
Device No participation

10.3 Feature 2: adding a pet

Feature description: Fill in the pet profile information and select/upload a pet avatar.

Corresponding design elements (form page):

  • Avatar selection area (centered at the top, large circular avatar selection box)
  • First row: preset emoji avatar grid (12 types: 🐶🐱🐰🐹🐸🐦, etc.)
  • Second row: "📷 Upload Image" button (custom image, within 1MB)
  • Pet name input box (2-20 characters)
  • Pet type selection (Dog / Cat / Other → secondary options)
  • Breed input box (optional)
  • Birthday picker (optional)
  • Gender selection (Male / Female / Unknown)
  • Save button
Dimension Description
App 🟢 Select an emoji avatar or upload a custom image (JPEG/PNG, within 1MB, compressed to 200KB on the App side) → fill in the form → POST /api/v1/pets
Server 🟢 Create the pet record → store the avatar image to OSS (when a custom avatar is used)
Device No participation

10.4 Feature 3: editing a pet

Feature description: Edit the profile information of an existing pet (avatar, name, type, breed, age, gender).

Corresponding design elements: Tap the pet card → edit form page (same content as adding, auto-filled with existing data)

Dimension Description
App 🟢 GET pet details → fill the form → PUT /api/v1/pets/{id}
Server 🟢 Update the pet record
Device No participation

10.5 Feature 4: deleting a pet

Feature description: Delete a pet profile and at the same time unlink it from feeding plans (pet_id is set to empty; the plan itself is not deleted).

Corresponding design elements: Pet card → delete button → confirmation dialog "Delete "Xiaobei"? After deletion, all associated feeding plans will be unlinked from this pet, but the plans themselves will not be deleted."

Dimension Description
App 🟢 Confirmation dialog → DELETE /api/v1/pets/{id} → refresh the list
Server 🟢 Delete the pet record → unlink the feeding plan association (set pet_id to empty)
Device No participation

10.6 Feature 5: pet feeding records

Feature description: Tap the "🍚 Feeding Records" button on the pet card to view the historical feeding records of that pet.

Corresponding design elements: Feeding record list page (in reverse chronological order):
- Each record: time label "April 23 08:05" + portion "30g" + feeding method label (manual/scheduled) + device name "Xiaobei's Feeder" + status (success ✅ / failed ❌)

Dimension Description
App 🟢 GET /api/v1/feeding-records?pet_id=xxx → list display → paginated loading
Server 🟢 Query the feeding records associated with pet_id and return them paginated in reverse chronological order
Device No participation

11. Module VII: Device settings

Corresponding page: Device settings page (device-settings-page)
Design mockup description: Top navigation bar "⚙️ Device Settings" + back button. Settings group list: Basic settings / Feeding settings / Camera settings / Voice settings / Device info / bottom danger zone (Unbind).

!image-20260423164556958

11.1 Module overview

Manage the configuration items of a single device, including basic settings, feeding settings, camera settings, voice settings and device information display.

11.2 Feature 1: basic settings

Feature description: Modify the device name, set the device location, and display the power supply mode.

Corresponding design elements:

  • Device name input box (tap to edit, the keyboard pops up)
  • Device location picker (6 preset options with circular icons: Living room / Bedroom / Balcony / Kitchen / Other)
  • Power supply mode display (plug-in icon 🔌 or battery icon 🔋 + percentage)
Dimension Description
App 🟢 Tap the device name → edit → PUT /api/v1/devices/{id} {device_name}; tap a location option → PUT /api/v1/devices/{id} {location}
Server 🟢 Update the device configuration → store it in the database → deliver it to the device side via MQTT (only device_name needs to be delivered to the device)
Device 🟢 Receive device_name → store it locally → the device display/LCD shows the name (if available)

11.3 Feature 2: feeding settings

Feature description: Set the default food portion (the initial value for manual feeding and new plans), the feeding sound switch, the food dispensing reminder switch and the low food level reminder threshold.

Corresponding design elements:

  • Default food portion slider (range 5-200g, step 5g, scale labels shown below)
  • Feeding sound switch (a prompt tone is played when dispensing food if enabled)
  • Food dispensing reminder switch (the App pushes a notification after dispensing if enabled)
  • Low food level reminder threshold slider (range 5%-50%, default 20%, with the text below "A reminder is sent when the food level is lower than this value")
Dimension Description
App 🟢 Adjust the slider/switch → save in real time (the API is called after 300ms debounce)
Server 🟢 Update the device configuration → deliver it immediately to the device side via MQTT
Device 🟢 Receive the configuration → store it in local Flash → apply the configuration each time food is dispensed

11.4 Feature 3: camera settings

Feature description: Set the video resolution, infrared night vision mode and recording quality.

Corresponding design elements:

  • Image resolution options: "Standard definition 640×480" (default) / "High definition 1280×720"
  • Infrared night vision options: "Auto" (switches automatically according to light) / "Always on" / "Off"
  • Recording quality options: "Standard quality" (default) / "High quality" (only available when the resolution is set to high definition)
Dimension Description
App 🟢 After selection, PUT /api/v1/devices/{id}/camera {resolution, night_vision_mode, record_quality}
Server 🟢 Update the configuration → deliver it to the device side via MQTT
Device 🟢 Receive the configuration → the camera module adjusts parameters (resolution switching requires a brief restart of the camera preview)

⭐ Camera Resolution Switching Notes:

Item Standard Definition Mode (Default) High Definition Mode
Resolution 640×480 1280×720
Device encoding bitrate 1Mbps (adaptive 512k-2M) Automatically reduces the bitrate when the network is poor
Device heating Normal May increase; prolonged use is not recommended
App data usage ~400MB/hour ~800MB/hour
Video file size ~5MB/30 seconds ~10MB/30 seconds
Server-side transcoding Standard definition HLS stream High definition HLS stream

11.5 Feature 4: voice settings

Feature description: Adjust the intercom volume, and enable/disable the device-side sound (speaker) and device-side microphone.

Corresponding design elements:

  • Intercom volume slider (0-100, default 80)
  • Device-side sound switch (the device can play the voice sent by the App when enabled)
  • Device-side microphone switch (the device can capture sound and send it to the App when enabled)
Dimension Description
App 🟢 Slider adjustments take effect in real time (the volume value is sent to the device) → switching a toggle calls the API
Server 🟢 Update the configuration → deliver it to the device side via MQTT
Device 🟢 Receive the volume value → apply it to the speaker output in real time; receive the toggle state → control whether audio is captured/played

11.6 Feature 5: device information

Feature description: Display read-only meta information such as the device model, firmware version, device ID, running time and cumulative feeding statistics.

Corresponding design elements:

  • Device model: PF200 (read-only text)
  • Device ID: PF200-ABC123 (read-only text, can be copied)
  • Firmware version: v2.1.0 (read-only text, tap to enter the firmware upgrade page)
  • Device SN: XSW20260408PF200 (read-only text)
  • Running time: 12 hours ("Has been running stably for 12 hours 5 minutes")
  • Cumulative feeding: 128 times in total / 3840g in total (read-only text)
Dimension Description
App 🟢 Request the device details API → display read-only information (the copy button calls the system copy function)
Server 🟢 Provide detailed device information (including firmware version, SN, running time, cumulative statistics)
Device 🟢 The device-side firmware stores the version information and carries it in the status report

11.7 Feature 6: firmware update (OTA)

Feature description: Detect new firmware versions, download and upgrade the device firmware.

Corresponding design elements (HTML lines 1900~1920, firmware upgrade page):
- Current version: v2.1.0 (displayed)
- Latest version: v2.2.0 (displayed if a new version exists) → new version description "Fixed several bugs and improved stability"
- Upgrade button (if a new version exists, shows "Check for updates" → "Upgrade now")
- Upgrade progress: download progress bar (0-100%) + status text "Downloading firmware…" "Upgrading… do not power off"

Dimension Description
App 🟢 GET /api/v1/devices/{id}/firmware → compare versions → when a new version exists, a dialog prompts "New version v2.2.0 found, upgrade now?" → the user confirms → download the firmware package (HTTPS segmented download, with resume support) → forward the firmware to the device via MQTT/TCP → display the upgrade progress → the device restarts after the upgrade completes → the App detects that the device is online → Toast "Upgrade successful"
Server 🟢 Provide the firmware version query interface → provide the firmware file download (CDN accelerated, segmented download with resume support)
Device 🟢 Receive the firmware package → verify the signature (RSA-2048 or AES verification) → write it to the Flash backup area → switch the boot partition after verification passes → restart → run the new firmware → report the new version number via MQTT

Firmware update specifications:

Item Specifications
Firmware package format .bin (with an RSA-2048 signature header)
Maximum firmware size 4MB
Signature verification The device side writes to Flash only after signature verification passes; otherwise the package is discarded
Upgrade method The App downloads it and forwards it to the device via MQTT (when the device is online); or the device connects directly to the OTA server to download
Resume support Supported (HTTP Range requests)
During the upgrade The device side stops streaming and feeding, and the display shows "Upgrading…"
Upgrade failure handling The device automatically rolls back to the old firmware (dual-partition design) and reports an upgrade failure log
Upgrade timeout If the device side does not complete the upgrade within 5 minutes, it is judged as a failure and a rollback is triggered

11.8 Feature 7: unbinding

Feature description: Remove the device from the current family and unbind the account from the device.

Corresponding design elements: The "🚨 Unbind" red button at the bottom of the device settings page (danger operation zone). After tapping:

  • Confirmation dialog "Unbind "Xiaobei's Feeder"? After unbinding, you will not be able to control this device through this App, and other family members will also lose access."
  • Second confirmation: enter the device name to confirm "Please enter "Xiaobei's Feeder" to confirm"
Dimension Description
App 🟢 Second confirmation by entering the device name → POST /api/v1/devices/{id}/unbind → clear the local device cache → return to the home page (device list empty state)
Server 🟢 Delete the device binding record → notify the device side to clear the pairing information (MQTT) → the device enters network configuration mode after clearing the pairing information
Device 🟢 Receive the unbind notification → clear the local user binding information → enter network configuration mode (fast blue flash)

12. Module VIII: Family management

Corresponding page: Family management page (family-page)
Design mockup description: Top navigation bar "👨‍👩‍👧 Family Management" + back button. Main area: current family information card (family name + number of members) + member list (avatar + nickname + role tag "Administrator★" / "Member") + "Invite Member" button at the top right. Bottom action area: "Edit Family Information" + "Disband Family" (administrator only, visible when there are no other members).

!image-20260423164717172

12.1 Module overview

Manage family units, including creating/editing family information, inviting/removing members, and setting member roles (administrator/member).

12.2 Feature 1: creating or editing a family

Feature description: Create a new family (fill in the name and address); administrators can edit family information.

Corresponding design elements:

  • Create family form: family name input box (required, 2-20 characters) + family address input box (optional)
  • Edit family form: same as creation, auto-filled with existing data
Dimension Description
App 🟢 Fill in the form → POST /api/v1/families or PUT /api/v1/families/{id}
Server 🟢 Create the family record → the creator automatically becomes the administrator (role=owner); only administrators are allowed to perform updates
Device No participation

12.3 Feature 2: inviting members

Feature description: Invite others to join the family through a QR code / invitation link.

Corresponding design elements:

  • Invitation page: family QR code (centered, can be saved to the album) + copy link button + share to WeChat/QQ buttons
  • Text below the QR code: "Scan the QR code to join "Xiaobei's Family"" "The invitation link is valid for 7 days"
Dimension Description
App 🟢 Display the family QR code (QRCode generation, containing the invitation link URL) → provide copy link sharing
Server 🟢 Generate a time-limited family invitation code (UUID, valid for 7 days, stored in Redis, TTL=604800s) → generate the invitation link URL → the invitee opens the App through the invitation link → the invitation code is filled in automatically → the user joins the family after confirmation, with the role defaulting to "Member"
Device No participation

Invitation specifications:

Item Specifications
Invitation code format UUID v4
Invitation valid 7 days (604800 seconds)
Invitation code usage count One-time (it becomes invalid immediately after joining)
Invitation method QR code (the URL contains the invitation code) / invitation link
Invitee role Defaults to "Member" (not administrator)
Invitation limit for administrators Unlimited

12.4 Feature 3: removing members

Feature description: Administrators can remove other members (confirmation dialog); members cannot remove themselves (they need to contact the administrator or leave the family).

Corresponding design elements: The "Remove" button on the right of each item in the member list (red text, administrator operation). After tapping:

  • Confirmation dialog "Remove "{member nickname}" from the family? After removal, this member will not be able to access all devices in the family."
Dimension Description
App 🟢 The administrator taps Remove → confirmation dialog → DELETE /api/v1/family-members/{member_id}
Server 🟢 Delete the member relationship → revoke that member's access permission to family devices
Device No participation

⭐ Permission Rule:

  • Administrators cannot remove themselves
  • A family must retain at least 1 administrator
  • If an administrator wants to leave the family, administrator permission must first be transferred to another member
  • Members can leave the family proactively (the "Leave Family" button is in the member's personal card)

13. Module IX: Message centre

Corresponding page: Message page (message-page)
Design mockup description: Top navigation bar "🔔 Messages" + "⚙️ Message Settings" button at the top right. Filter tabs: "All / Feeding / Device / System". The main body is a message list. Each message card: left icon (🔔 feeding / ⚠️ device / 📢 system) + message title (bold) + message summary (small gray text) + time label (on the right, "3 minutes ago" / "Yesterday"). Unread messages have a blue vertical bar marker on the left.

!image-20260423164807542

13.1 Module overview

Centrally display system push notifications, including feeding completion notifications, device alarm notifications, family member change notifications, system announcements, etc.

13.2 Feature 1: message list

Feature description: Display messages in reverse chronological order, supporting filtering by type (All/Feeding/Device/System). Unread messages have a blue vertical bar marker on the left.

Corresponding design elements:

  • Message list: each message card + unread blue vertical bar + title + summary + time
  • Filter tabs (All/Feeding/Device/System)
  • Message details page: tap a card → enter the details page (full-screen message content + related action buttons)
Dimension Description
App 🟢 Request the message list (GET /api/v1/messages?type=all/feed/device/system&page=1&limit=20) → list display → tap to mark as read → pull down to refresh, pull up to load more
Server 🟢 Query the user's message records (all messages under the associated family_id) → return paginated in reverse chronological order
Device No participation

Message read policy:
- When the App enters the message list page, all messages on the current screen are silently marked as read (batch PATCH)
- When entering the details page of a single message, that message is individually marked as read
- The message icon in the bottom tab bar shows a red dot with the unread count (updated in real time)

13.3 Feature 2: message push triggers

Feature description: The server generates and pushes messages according to the event type, and at the same time pushes them to the App through the JPush/Umeng/self-built Push channel.

Trigger Scenario Message Type Push Title Push Content Example Message Card Icon
Manual feeding completed Feeding 🍚 Feeding Completed "Xiaobei's Feeder has dispensed 30g of food" 🍚
Scheduled plan execution completed Feeding ⏰ Scheduled Feeding "08:00 scheduled feeding of 30g completed" ⏰
Scheduled plan execution failed Feeding ⚠️ Feeding Abnormal "08:00 scheduled feeding failed: food jam detected" ⚠️
Food level below the threshold Device Alarm ⚠️ Insufficient Food "Xiaobei's Feeder has only 15% food left, please refill in time" ⚠️
Device online Device status 🟢 Device Online "Xiaobei's Feeder is connected to the network" 🟢
Device offline Device status 🔴 Device Offline "Xiaobei's Feeder is offline, please check" 🔴
Device battery low Device Alarm 🔋 Low Battery "Xiaobei's Feeder has only 10% battery left, please charge" 🔋
Firmware upgrade completed Device Update ✨ Firmware Upgrade "Xiaobei's Feeder has been upgraded to v2.2.0" ✨
New member joined Family Notification 👋 New Member "Mom has joined the family "Xiaobei's Family"" 👋
Member removed Family Notification 👋 Member Change "You have been removed from the family "Xiaobei's Family"" 👋
App update System Notification 📱 Update Prompt "App has been updated to the latest version v1.0.1, tap to view" 📱

13.4 Feature 3: message settings

Feature description: Users can toggle various message notifications (feeding reminders, low food level reminders, device offline reminders, low battery reminders, do-not-disturb mode).

Corresponding design elements (message settings page):

  • Feeding reminder switch (enabled by default)
  • Low food level reminder switch (enabled by default)
  • Device status reminder switch (enabled by default)
  • Low battery reminder switch (enabled by default)
  • Do-not-disturb period switch (disabled by default): when enabled, a time picker "22:00 - 08:00" is displayed
Dimension Description
App 🟢 Switch toggle → PUT /api/v1/users/{id}/notification-settings
Server 🟢 Store the user's notification preferences → check the user settings when sending pushes
Device No participation

Do-not-disturb period specifications:
- Disabled by default
- When enabled: 22:00 - 08:00 (the start and end times can be customized)
- During the do-not-disturb period: feeding reminders, device status reminders and low battery reminders are suspended Feeding reminders, device status alerts, low-battery alerts
- : severe low food level alarms (<10%) and device error_code values of high severity are pushed forcibly even during the do-not-disturb period: hard warning (<[0)] low food levels and equipment error code at a high level, even when forced to deliver during undisturbed hours

14. Module X: Device networking and binding

Corresponding page: device-add pages (add-device-page / add-method-page / bluetooth-add-page / wifi-add-page)
Design mockup description: Top navigator "Putting Device" + Return button. The main subject is a web-based guide page: the step indicator "1 Select 2 Connect Device 3 Done". Below are two large card options: "The Bluetooth Add (Recommended)" plus "The WiFi Add.".

!image-20260423164854799

14.1 Module overview

Users add new devices to App to support Bluetooth Add (recommended) and WiFi add in two ways. The equipment distribution network is a critical process for users for the first time.

14.2 Feature 1: choosing how to add a device

Feature description: Lead the user to choose Bluetooth Add or WiFi Add and recommend Bluetooth ways.

Corresponding design elements:

  • Two large, parallel cards: "The Bluetooth Add (Recommended)"+ "The WiFi Add"
  • Bluetooth card belt "Recommended" label (Green Small Tab)
  • Click on the card to enter the matching network process
Dimension Description
App → Shows two additions to the card → Tests for cell phone bluetooth state (directed to open if not) → User selects and enters the corresponding process
Server No participation
Device No participation

14.3 Feature 2: adding over Bluetooth (recommended)

Feature description Search for and connect to nearby equipment through BLE (low-powered bluetooth) and complete installation network and account binding.

Corresponding design elements:

  • Step 1: power on the device → "Press and hold the reset button for 3 seconds; rapid blue flashing means it has entered pairing mode"
  • Step 2: search device → show BLE scan animation (roop spread) + list of devices found (name: 'XSW-PF200-AB12 ')
  • Step 3: connecting → progress messages "Connecting…", "Joining the network…", "Bound successfully"
  • Completed Page: Device Picture + "Bay's Feeder Added Success" + "See" button
Dimension Description
App 🟢 BLE scan (filtered by device name prefix XSW-PF200) User click to select the device → BLE connection → Send a network command → Device connection WiFi and MQTT → App exchange authentication information with the device → Call binding API
Server → Create device binding record (device id + user id + family id)
Device 🟢BLE Receives Network Command → Connection Specifies WiFi (SSid/cipher sent by App through BLE) Connect to Cloudside MQTT Server → Validation Matching → Send Device Authentication Information

Device indicator states (throughout Bluetooth pairing):

Phase Indicator light status Duration
Factory state (not provisioned) Slow blue blink (2 Hz) Continuous
Connecting over BLE Fast blue blink (5 Hz) Until the BLE connection succeeds
Connecting over Wi-Fi Steady blue Until the Wi-Fi connection succeeds
Connecting to MQTT Fast green blink Until the MQTT connection succeeds
Pairing succeeded Steady green Off after 3 seconds
Pairing failed Red blinks three times Then the factory-state indicator resumes

14.4 Feature 3: adding over Wi-Fi

Feature description Networking and binding (options when blue teeth are not available) through equipment hotspot connection to WiFi network.

Corresponding design elements:

  • Step 1: power on the device → "Press and hold the reset button for 3 seconds; the indicator flashes blue rapidly"
  • Step 2: Connect device hotspots → Description of "connecting in WiFi settings"
  • Step 3: choose WiFi → the app lists the phone's current WiFi networks; the user picks the home network and enters the password
  • Step 4: provisioning → progress bar "Configuring…"
  • Finish Page: Add Same Bluetooth
Dimension Description
App → Direct user connection device hotspots (App Opens the WiFi Settings page)→ Retrieving the user input's WiFi SID/ passwords sent to the device hotspots via HTTP → When the device connects to the real WiFi get IP → App detected online on the device → Tie API
Server Add with Bluetooth
Device 🟢 Device Open Hotspots (SoftAP)

15. Module XI: Mine (profile)

Corresponding page: mine page (profile-page / mine-page)
Design mockup description: Top navigator "My" or user + nickname area. The subject is the menu list: Message Notification / Home Management / Account Security / Clear Cache / About us / Exit Login. Bottom displays the App version number.

!image-20260423164929006

15.1 Module overview

Displays user information, provides account number security, notification settings, cache clean-up, access to assistive functions, etc.

15.2 Feature 1: profile information

Feature description: display of user profiles, nicknames, cell phone numbers (sensitization), number of families.

Corresponding design elements:

  • User header (round, click-ed)
  • Nickname (Bolder)
  • Masked mobile number display (138****1234)
  • Family count ("Family ×2")
Dimension Description
App • Request user details API (GET /api/v 1/user/me) display personal information
Server Returns complete user information (heads URL, nickname, cell phone number dissensitisation, family list)
Device No participation

15.3 Feature 2: account security

Feature description: change passwords, bind tweets, set biometric login (see module 1 5.5 account security).

15.4 Feature 3: notification settings

Feature description: toggles each type of notification (see module 9, 13.4 Notification settings).

15.5 Feature 4: clearing the cache

Feature description: One-click to clean up the App local cache (abbreviations, temporary files).

Corresponding design elements:

  • Current Cache Size Display (e. g. 'current cache')
  • Clean Cache button (click to show cleanup progress and clear cleanup after completion)
Dimension Description
App 🟢 Measure the size of the local cache directory → the user taps Clean → delete the local thumbnail cache, temporary files and failed uploads awaiting retry → show the size after cleaning (usually 0 MB or very small)
Server No participation
Device No participation

Cleanup scope:

Cache Type Cleanup Policy
Thumbnail Cache Clear album thumbnail cache (redownload next time)
Temporary file Video ad hoc file to clean failed upload (not retained successfully uploaded)
Snap Preview Cache Cleans up locally generated JPEG preview files (surnamed successfully uploaded)
Login Token Do not clear (maintain login status)
Local Device Data Not cleared (maintain device cache, next start faster)

15.6 Feature 5: about us

Feature description: Presentation of App version number, user protocols, privacy policy, client contact information.

Corresponding design elements:

  • App logo + version (v1.0.0 build 20260423)
  • User Protocol Link
  • Privacy policy link
  • Guest Mailbox / Telephone

15.7 Feature 6: signing out

Feature description: Clear local login status, return login page.

Corresponding design elements: Bottom Exit Login button (red text)

Dimension Description
App 🟢 A confirmation dialog appears ("Sign out?"); once confirmed the local token is cleared → the app returns to the sign-in page
Server Deactivate current refresh token (Redis delete key)
Device No participation

Appendix

A. Summary of key specifications for video streams and media files

Item Specifications
Device Push Protocol RTMP (rtmp://media.xswei.com/live/{device_id})
App Draw HLS(.m]3u +.ts fraction, 4 seconds per piece, 8 pieces cache)
Video Markup Rate [Optically]
Video High Clear Rate [Optically]
Device Encoded H.264 Main Profile
Audio encoding kbps mono
End-to-end video delay ≤3 s (standard definition) / ≤4 s (high definition)
Capture Image Resolution JPEG, MASS
Snap Picture Size ~200KB
Video Resolution 640×480 H.264 + AAC
The longest video time Seconds
Video file size ~5MB
Video Upload HTTPS multipart, part upload to support breakpoint Pass
Photo user ceiling 50 sheets
Video user ceiling 5 Paragraph (ultra automatic deletion of earliest)
Long time spent saving photos 7 days
Video saving time Day

B. MQTT topic specification

Topic Mode Orientation Description
device/{device_id}/status Device → server Periodic reporting of equipment status (30 seconds/s)
device/{device_id}/feed Server → device Manual Feeding Command
device/{device_id}/feed/result Device → server Report the results of the feeding
device/{device_id}/feed/batch-report Device → server Batch feeding records reported during offline
device/{device_id}/plan/update Server → device List of feeding schemes (full)
device/{device_id}/plan/delete Server → device Delete a feeding scheme
device/{device_id}/config Server → device Release Device Configuration Update
device/{device_id}/ota Server → device OTA firmware update command
device/{device_id}/unbind Server → device Notification of untie

C. Error code summary

Error Code Description App Process
ERR_PHONE_INVALID Cell phone format is incorrect Enter box red hint
ERR_PHONE_NOT_REGISTERED The cell phone is not registered Toast, please register the account
ERR_CODE_INVALID Authentication code error Enter box dithering, left n chance hint
ERR_CODE_EXPIRED Authentication code expired Toast Hint "Certification Code Expired, Retrieving"
ERR_CODE_LOCKED It's too frequent. Please try again in a minute Fullscreen mask hint countdown
ERR_NETWORK Network error Toast hint "Web anomaly. Check the network."
ERR_DEVICE_OFFLINE Device offline Toast hint "Equipment offline, check the network"
ERR_DEVICE_NO_RESPONSE Device does not respond Toast hint "The device is not responding. Check the network."
ERR_LOW_FOOD There's not enough food left Eject confirmation hint, "Is the food surplus insufficient
ERR_PLAN_LIMIT Number of plans reached ceiling Toast hint "to create up to 20 plans"
ERR_NO_PERMISSION No permission to operate Toost Hint "You do not have permission to do this"
← Data Storage & Device Status DescriptionDocs CenterDevicePlay Voice →
Device plays voice →
Didn't find what you need?Contact us, talk to our engineers directly.
, talk to our engineers directly.

Request a Quote

Fill in the form and we will get back with a quote and proposal within 1 business day.

Click "Generate inquiry email" to open your mail client with the body pre-filled. If no mail client is configured, click "Copy" and paste it into webmail — recipient: sunshiyang@xstrive.com.