meow-micropython 0.2.0

MicroPython SDK for the Meow Meow Scratch® API

Send sensor data and read/write device state from an ESP32, Raspberry Pi Pico W, or any other MicroPython board.

Docs · Getting Started · Boards · API Reference

This is a lean, device-focused SDK with no external Python dependencies. It talks HTTP(S) directly over usocket/ussl and covers reading and writing data from a running board. Managing apps, endpoints, fields, dashboards, webhooks, and plan limits is a one-time setup step best done from the web app or the full Python SDK (meow-sdk) on your computer.

Install

Use MicroPython 1.24 or newer. The package installs meow.py and the production CA certificate used to verify https://meowmeowscratch.com. The bundled ISRG Root X1 certificate comes from Let’s Encrypt, and its fingerprint is checked by the release script.

import mip
mip.install("github:meowmeowscratch/meow-micropython")

# or pin an exact release:
mip.install("github:meowmeowscratch/meow-micropython", version="v0.2.0")

You can also install over USB:

mpremote mip install github:meowmeowscratch/meow-micropython

For a manual install, copy both files into the same directory on the board:

mpremote fs cp meow.py :/lib/meow.py
mpremote fs cp isrg-root-x1.pem :/lib/isrg-root-x1.pem

Or from PyPI, for desktop-side testing/simulation before flashing to a board (this does not work on an actual MicroPython board — there's no pip there; boards must use one of the methods above):

pip install meow-micropython

from meow import Meow  # same import as on-device

30-second quickstart

from meow import Meow

# Connect to Wi-Fi and set the board clock first (see examples/).

api = Meow(api_key="YOUR_APP_API_KEY")
api.send("weather-station", "readings", {
    "temperature": 22.5,
    "humidity": 65,
})

data = api.records("weather-station", "readings", limit=10)
print(data["results"])

Create an app-scoped key for the board from the app in meowmeowscratch.com. Never store a platform token on a device: it grants account-wide access and is unnecessary here.

Read public data (no key needed)

api = Meow(username="jake")
data = api.get("weather-station", "readings")
print(data)

Sensor loop example (DHT22)

See examples/dht22_weather_station.py for a complete Wi-Fi + sensor + send loop.

Dashboard control example

Build a dashboard with a toggle widget bound to an endpoint's static payload, then flip it from your phone — the board polls it and drives a real LED. See examples/dashboard_led_control.py.

API reference

Reading data

• get(app, endpoint, **filters) — read a public endpoint (requires username)
• get_record(app, endpoint, record_id)
• aggregate(app, endpoint, aggregates, field=None, **filters)
• records(app, endpoint, limit=25, offset=0) — requires api_key
• all_records(app, endpoint) — auto-paginates; mind the RAM on constrained boards

Writing data

• send(app, endpoint, data)
• send_many(app, endpoint, records) — up to 100 at once
• update(app, endpoint, record_id, data)
• delete_record(app, endpoint, record_id)

Device control state

• get_payload(app, endpoint) / get_payload_state(app, endpoint)
• set_payload(app, endpoint, data)

Public dashboards

• public_dashboard(share_token) — read-only; no API key required

Credential diagnostics

• auth_context() — confirm the key type, app, and scopes without exposing it

Errors

All errors are subclasses of MeowError (AuthError, NotFoundError, ValidationError, RateLimitError), each carrying .status_code, .code, .field, and .hint when the server provides them — same shape as the Python SDK's exceptions.

from meow import Meow, MeowError

try:
    api.send("weather-station", "readings", {"temperature": 22.5})
except MeowError as e:
    print("send failed:", e)

Notes for constrained boards

• Each call opens and closes its own socket (Connection: close) — there's no connection pooling, to keep memory use predictable.
• HTTPS certificates are verified by default. Set the board clock with ntptime.settime() before the first API request. The bundled CA covers meowmeowscratch.com; pass ca_cert="/path/to/your-ca.pem" for a custom HTTPS base_url.
• HTTPS verification cannot be disabled. Use an http:// base_url only for a local development server with a disposable development key.
• all_records() loads every page into memory — fine for a few hundred rows, risky on an 8KB-RAM board with thousands of records. Prefer records() with pagination for large collections.

Links

• Full documentation
• API reference
• Boards guide
• Python SDK for Raspberry Pi / desktop
• PyPI

License

MIT