Xiaotieba / Zectrix E-Ink Device

Overview

小贴吧（Xiaotieba / Zectrix smart sticky note）是一类通过云端 Open API 控制的 4.2 英寸电子墨水屏设备。这个 skill 帮助你：

• 配置 API 凭证和设备 ID/MAC；
• 获取设备列表；
• 向 1-3 个页面推送纯文本、结构化文本或图片；
• 管理云端待办事项；
• 设计适合 400×300 电子墨水屏的短文本版式；
• 为天气、课程表、家庭提醒、会议提醒等场景设计定时推送；
• 排查“API 成功但设备没刷新”“密钥截断”“内容过长显示不全”等问题。

This skill is intentionally credential-free. Never publish real API keys, device MACs, family names, schedule details, or private reminder content inside the skill package.

When to Use

Use this skill when the user asks to:

• “配置小贴吧 / 智能便利贴 / Zectrix 电子墨水屏”；
• “推送文字/图片到小贴吧”；
• “做天气/作业/课程/待办提醒屏”；
• “查小贴吧设备列表”；
• “管理小贴吧待办”；
• “小贴吧没收到推送 / 显示不完整 / 定时任务没执行”；
• build scheduled reminders for a small e-paper display.

Do not use this skill for unrelated e-paper hardware that has no Zectrix/Xiaotieba cloud API compatibility.

Device Facts

Typical device profile:

Always verify the actual device list before pushing.

Configuration

Environment Variables

Recommended variable names:

export XIAOTIEBA_API_BASE="https://cloud.zectrix.com/open/v1"
export XIAOTIEBA_API_KEY="<your-api-key>"
export XIAOTIEBA_DEVICE_ID="<device-mac-or-id>"

If a script supports multiple devices, use explicit names:

export XIAOTIEBA_HOME_DEVICE_ID="<device-id>"
export XIAOTIEBA_OFFICE_DEVICE_ID="<device-id>"

Local Config File Pattern

For cron jobs or scripts, keep secrets outside the skill and outside git:

mkdir -p ~/.config/xiaotieba
chmod 700 ~/.config/xiaotieba
cat > ~/.config/xiaotieba/config.env <<'EOF'
XIAOTIEBA_API_BASE=https://cloud.zectrix.com/open/v1
XIAOTIEBA_API_KEY=<your-api-key>
XIAOTIEBA_DEVICE_ID=<device-mac-or-id>
EOF
chmod 600 ~/.config/xiaotieba/config.env

Then scripts can load it:

set -a
. "$HOME/.config/xiaotieba/config.env"
set +a

API Quick Reference

Base URL:

https://cloud.zectrix.com/open/v1

Authentication header:

X-API-Key: <your-api-key>

Device Management

Example:

curl -fsS "$XIAOTIEBA_API_BASE/devices" \
  -H "X-API-Key: $XIAOTIEBA_API_KEY"

Expected success shape may look like:

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "deviceId": "AA:BB:CC:DD:EE:FF",
      "alias": "zectrix-s3-epaper-4.2"
    }
  ]
}

Display Push

Plain Text Push

curl -fsS -X POST "$XIAOTIEBA_API_BASE/devices/$XIAOTIEBA_DEVICE_ID/display/text" \
  -H "X-API-Key: $XIAOTIEBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "🌤️ Today\n\nSunny, light jacket.\nRemember the 15:00 meeting.",
    "fontSize": 20,
    "pageId": "1"
  }'

Expected success shape:

{
  "code": 0,
  "msg": "success",
  "data": {
    "totalPages": 1,
    "pushedPages": 1
  }
}

Structured Text Push

curl -fsS -X POST "$XIAOTIEBA_API_BASE/devices/$XIAOTIEBA_DEVICE_ID/display/structured-text" \
  -H "X-API-Key: $XIAOTIEBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Meeting",
    "body": "15:00 Room 3\nBring laptop",
    "fontSize": 16,
    "pageId": "1"
  }'

If this returns a 5xx error, switch to /display/text and include the title inside text.

Image Push

API variants may differ. A common multipart pattern is:

curl -fsS -X POST "$XIAOTIEBA_API_BASE/devices/$XIAOTIEBA_DEVICE_ID/display/image" \
  -H "X-API-Key: $XIAOTIEBA_API_KEY" \
  -F "images=@/path/to/image.png" \
  -F "dither=true" \
  -F "pageId=1"

For best results, pre-render images at 400×300 px and use high-contrast black/white or grayscale dithering.

Todo API

Create todo example:

curl -fsS -X POST "$XIAOTIEBA_API_BASE/todos" \
  -H "X-API-Key: $XIAOTIEBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Buy milk",
    "description": "On the way home",
    "dueDate": "2026-03-20",
    "dueTime": "18:30",
    "repeatType": "none",
    "priority": 2,
    "deviceId": "AA:BB:CC:DD:EE:FF"
  }'

Layout Guidelines for 400×300 E-Paper

E-paper is not a phone screen. Optimize for fast reading and limited refresh.

Text Rules

• Keep titles under 12-16 Chinese characters or 20 English letters.
• Keep each line short: about 12-16 Chinese characters or 24-30 English characters.
• Prefer 5-8 lines total.
• Keep important content at the top.
• Use emoji sparingly; test the actual glyph rendering.
• Avoid dense tables unless rendered as an image.
• For Chinese reminders, use short action phrases rather than full paragraphs.

Suggested Plain Text Template

🌤️ Today
06 月 12 日 (周五)

Warmer than yesterday
Light jacket is enough
Good drying window: noon

Updated 06:00

Three-Page Reminder Pattern

A useful convention for 3-page devices:

If a page’s source data is missing, push a clear fallback instead of leaving stale content on the display.

Scheduled Push Pattern

For deterministic recurring pushes, use a script plus cron/Hermes cron rather than asking the model to remember state.

Example script push-xiaotieba-text.sh:

#!/usr/bin/env bash
set -euo pipefail

CONFIG="$HOME/.config/xiaotieba/config.env"
if [[ ! -f "$CONFIG" ]]; then
  echo "missing config: $CONFIG" >&2
  exit 1
fi
set -a
. "$CONFIG"
set +a

PAGE_ID="${1:-1}"
TEXT="${2:-Test message}"

python3 - <<'PY' "$XIAOTIEBA_API_BASE" "$XIAOTIEBA_API_KEY" "$XIAOTIEBA_DEVICE_ID" "$PAGE_ID" "$TEXT"
import json, sys, urllib.request
base, key, device, page, text = sys.argv[1:6]
payload = json.dumps({"text": text, "pageId": str(page)}, ensure_ascii=False).encode("utf-8")
url = f"{base.rstrip('/')}/devices/{device}/display/text"
req = urllib.request.Request(
    url,
    data=payload,
    headers={"X-API-Key": key, "Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(req, timeout=20) as resp:
    body = resp.read().decode("utf-8", "replace")
print(body)
PY

Cron examples:

# Morning page
0 6 * * * /path/to/push-morning-summary.sh

# Task page
0 17 * * * /path/to/push-task-summary.sh

# Tomorrow schedule page
10 17 * * * /path/to/push-tomorrow-schedule.sh

Troubleshooting

“API returned success but device did not update”

Checklist:

1. Wait 15-30 seconds; e-paper refresh can be slow.
2. Confirm the target deviceId from GET /devices.
3. Confirm pageId is valid (1, 2, or 3).
4. Push a very short test message to page 1.
5. Check whether the device is online in the vendor app or API device list.
6. Avoid pushing repeatedly within a very short interval; allow at least 2-3 minutes for scheduled jobs unless the vendor documents otherwise.

“Authentication failed / no devices returned”

1. Confirm XIAOTIEBA_API_KEY is set and complete.
2. Look for accidental truncation such as abc...xyz; scripts must contain the full value or load it from a secure config file.
3. Ensure the shell actually loads ~/.config/xiaotieba/config.env.
4. Check file permissions: chmod 600 ~/.config/xiaotieba/config.env.

“Structured text returns 500”

Use plain text:

Title

Body line 1
Body line 2

and send it via /display/text.

“Content is cut off”

1. Shorten the text to the top 5-8 lines.
2. Reduce line width.
3. Remove low-value details and exact numbers.
4. Render a custom 400×300 image if precise layout matters.

“Cron did not run”

1. Check the cron entry with crontab -l or the Hermes cron list.
2. Use absolute script paths in system cron.
3. Make scripts executable: chmod +x script.sh.
4. Ensure the script loads credentials because cron has a minimal environment.
5. Write logs to a known path and inspect them.

Security and Privacy

• Never put real API keys, device IDs, MAC addresses, family names, school schedules, or private reminders into the published skill.
• Keep credentials in environment variables or ~/.config/xiaotieba/config.env with mode 0600.
• Redact API keys and device IDs in logs before sharing.
• Treat reminder contents as private. Ask before sending them to public channels or group chats.
• When publishing examples, use placeholders such as and AA:BB:CC:DD:EE:FF.

Common Pitfalls

1. Hardcoding secrets in scripts or skills. Use env vars or a local config file.
2. Using structured text as the default. Plain text is usually more reliable.
3. Overloading a small e-paper screen. Short, readable summaries beat dense data.
4. Forgetting pageId. The push may land on an unexpected page or default page.
5. Cron environment mismatch. A command works interactively but fails in cron because env vars are missing.
6. Too-frequent pushes. E-paper refresh and cloud queues are slower than chat apps.
7. Publishing personal schedules. Replace real reminders with generic examples.

Verification Checklist

• [ ] GET /devices returns the expected device list.
• [ ] A short plain-text test push returns code: 0 or HTTP success.
• [ ] The device physically refreshes to show the test message.
• [ ] Each scheduled script loads credentials from a protected local file or env vars.
• [ ] Long messages are shortened or rendered as a 400×300 image.
• [ ] Logs do not contain API keys or private reminder text.
• [ ] Published skill package contains no real API keys, device IDs, MACs, family details, or local-only paths.