Metadata-Version: 2.4
Name: meow-micropython
Version: 0.1.0
Summary: MicroPython SDK for the Meow Meow Scratch API — ESP32 and Raspberry Pi Pico W boards.
Project-URL: Homepage, https://github.com/meowmeowscratch/meow-micropython
Project-URL: Documentation, https://meow-micropython.readthedocs.io
Project-URL: Repository, https://github.com/meowmeowscratch/meow-micropython
Author-email: Meow Meow Scratch <meowmeowscratch@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,education,esp32,iot,kids,micropython,raspberry-pi-pico
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Embedded Systems
Requires-Python: >=3.8
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://meowmeowscratch.com/meowmeowscratch-text.svg" alt="Meow Meow Scratch" width="300" />
</p>

<h3 align="center">MicroPython SDK for the Meow Meow Scratch® API</h3>

<p align="center">
  Send sensor data and read/write dashboard controls from an ESP32, Raspberry Pi Pico W,
  or any other MicroPython board.
</p>

<p align="center">
  <a href="https://pypi.org/project/meow-micropython/"><img src="https://img.shields.io/pypi/v/meow-micropython?color=black&label=pypi" alt="PyPI"></a>
  <a href="https://github.com/meowmeowscratch/meow-micropython/releases"><img src="https://img.shields.io/github/v/release/meowmeowscratch/meow-micropython?color=black&label=release" alt="Release"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/meowmeowscratch/meow-micropython?color=black" alt="License"></a>
</p>

<p align="center">
  <a href="https://meow-micropython.readthedocs.io">Docs</a> &middot;
  <a href="https://meow-micropython.readthedocs.io/getting-started/">Getting Started</a> &middot;
  <a href="https://meow-micropython.readthedocs.io/boards/">Boards</a> &middot;
  <a href="https://meow-micropython.readthedocs.io/api-reference/">API Reference</a>
</p>

---

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](https://meowmeowscratch.com) or the
[full Python SDK](https://github.com/meowmeowscratch/meow-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](https://thonny.org),
[mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html), 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:

```python
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
```

```python
from meow import Meow  # same import as on-device
```

## 30-second quickstart

```python
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](https://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)

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

## Sensor loop example (DHT22)

See [`examples/dht22_weather_station.py`](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`](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.

```python
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](https://meow-micropython.readthedocs.io)
- [API reference](https://meow-micropython.readthedocs.io/api-reference/)
- [Boards guide](https://meow-micropython.readthedocs.io/boards/)
- [Python SDK for Raspberry Pi / desktop](https://github.com/meowmeowscratch/meow-sdk)
- [PyPI](https://pypi.org/project/meow-micropython/)

## License

MIT
