meow-micropython 0.1.0

MicroPython SDK for the Meow Meow Scratch® API

Send sensor data and read/write dashboard controls 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 — a single file (meow.py) with no external dependencies, talking HTTP(S) directly over usocket/ussl. It covers reading and writing data from a running board. Managing apps, endpoints, fields, dashboards, and webhooks is a one-time setup step best done from the web app or the full Python SDK (meow-sdk) on your computer.

Install

Simplest: copy the file. Take meow.py from this repo and copy it onto your board with Thonny, mpremote, or ampy — however you already move files to your board.

mpremote cp meow.py :meow.py

Or with mip (MicroPython's package manager), once connected to Wi-Fi on-device:

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

# or pin an exact release:
mip.install("github:meowmeowscratch/meow-micropython/meow.py@v0.1.0")

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 first (see examples/ for a wifi_connect() helper).

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"])

Get your API key at meowmeowscratch.com under Account > Platform Tokens, or an app-scoped key so a device can only reach that one app.

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)

Dashboards (read + control only — build/edit dashboards from the web app)

• dashboard_data(dashboard) / dashboard_state(dashboard)
• set_dashboard_widget_value(dashboard, widget_uuid, value)
• dashboard_patch(dashboard, endpoint_uuid, key_path, value)
• public_dashboard(share_token) — no API key required

Account

• limits() / auth_context()

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 is used by default (matching https://meowmeowscratch.com) via ussl.wrap_socket; certificate verification depends on your board's MicroPython build. Point base_url at a plain http:// address (e.g. a local nginx on your LAN during development) to skip TLS entirely.
• 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