Metadata-Version: 2.4
Name: meow-micropython
Version: 0.2.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 device state 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 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](https://meowmeowscratch.com) or the
[full Python SDK](https://github.com/meowmeowscratch/meow-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](https://letsencrypt.org/certificates/),
and its fingerprint is checked by the release script.

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

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

## 30-second quickstart

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

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

**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.

```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 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](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
