# Fostrom Device SDK for Python
[Fostrom](https://fostrom.io) is an IoT Cloud Platform built for developers. Monitor and control your fleet of devices, from microcontrollers to industrial IoT. Designed to be simple, secure, and fast. Experience first-class tooling with Device SDKs, type-safe schemas, programmable actions, and more.
The Fostrom Device SDK for Python works with Python 3.10+ and helps you quickly integrate, start monitoring, and controlling your IoT devices in just a few lines of code.
## Installation
```bash
pip install fostrom
```
## Quick Start
```python
from fostrom import Fostrom, Mail
# Create SDK instance
fostrom = Fostrom({
"fleet_id": "<your-fleet-id>",
"device_id": "<your-device-id>",
"device_secret": "<your-device-secret>",
"env": "<dev|test|prod>",
})
# Setup mail handler for incoming messages
def handle_mail(mail: Mail):
print(f"Received: {mail.name} ({mail.id})")
mail.ack() # Acknowledge the message
fostrom.on_mail = handle_mail
# Start the Device Agent and event stream
fostrom.start()
# Send sensor data
fostrom.send_datapoint("sensors", {
"temperature": 23.5,
"humidity": 65,
})
# Send status messages
fostrom.send_msg("status", {"online": True})
```
## API Reference
### Fostrom Class
#### `__init__(config)`
Create a new Fostrom instance.
**Parameters:**
- `config` (dict): Configuration dictionary with:
- `fleet_id` (str): Your fleet ID
- `device_id` (str): Your device ID
- `device_secret` (str): Your device secret
- `log` (bool, default: True): Enable logging (default: True)
- `env` (str, default: PYTHON_ENV || "dev"): Runtime Environment
- `stop_agent_on_exit` (bool, default: False): If True, `shutdown()` will stop the Device Agent too.
#### `start() -> None`
Start the Device Agent in the background and connect to it.
#### `shutdown(stop_agent: bool = False) -> None`
Stop the background event processing. If `stop_agent=True`, also stops the Device Agent.
#### `send_datapoint(name: str, payload: dict) -> None`
Send a datapoint to Fostrom.
#### `send_msg(name: str, payload: dict | None) -> None`
Send a message to Fostrom. Pass `None` if the schema has no payload.
#### `mailbox_status() -> dict`
Get current mailbox status.
#### `next_mail() -> Mail | None`
Get the next mail from the mailbox.
### Mail Class
#### Properties
- `id` (str): Mail ID
- `name` (str): Mail name/type
- `payload` (dict): Mail payload data
- `mailbox_size` (int): Current mailbox size
#### Methods
- `ack()`: Acknowledge the mail
- `reject()`: Reject the mail
- `requeue()`: Requeue the mail
## Device Agent
The Fostrom Device SDK downloads and runs the Fostrom Device Agent in the background. The Device Agent is downloaded automatically when the package is installed. The Device Agent starts when `fostrom.start()` is called and handles all communication with the Fostrom platform. The Device Agent runs continuously in the background, even after your Python program has terminated, to ensure that when your process manager restarts your Python program, it connects to the Device Agent right away. In case you want to stop the Device Agent when your program terminates, you can pass `stop_agent_on_exit: True` to the config.
## Logging
The SDK logs via Python's `logging` module using the `fostrom` logger. By default, WARNING/ERROR/CRITICAL are visible; INFO is not.
To see INFO messages (e.g., "Connected"), enable logging:
```python
import logging
logging.basicConfig(level=logging.INFO)
```
## Links
- **Fostrom Platform**: [https://fostrom.io](https://fostrom.io)
- **Documentation**: [https://docs.fostrom.io/sdk/py](https://docs.fostrom.io/sdk/py)
- **Python SDK**: [https://pypi.org/project/fostrom/](https://pypi.org/project/fostrom/)
Raw data
{
"_id": null,
"home_page": null,
"name": "fostrom",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "actions, cloud, datapoint, device, fleet, fostrom, hardware, iot, message, mqtt, raspberry, sdk, websockets",
"author": null,
"author_email": "Fostrom <support@fostrom.io>",
"download_url": "https://files.pythonhosted.org/packages/a9/00/e5b6a9062cd52ace758689c4011b4115a5b86c21d93be224fa62ce13fddf/fostrom-0.0.14.tar.gz",
"platform": null,
"description": "# Fostrom Device SDK for Python\n\n[Fostrom](https://fostrom.io) is an IoT Cloud Platform built for developers. Monitor and control your fleet of devices, from microcontrollers to industrial IoT. Designed to be simple, secure, and fast. Experience first-class tooling with Device SDKs, type-safe schemas, programmable actions, and more.\n\nThe Fostrom Device SDK for Python works with Python 3.10+ and helps you quickly integrate, start monitoring, and controlling your IoT devices in just a few lines of code.\n\n## Installation\n\n```bash\npip install fostrom\n```\n\n## Quick Start\n\n```python\nfrom fostrom import Fostrom, Mail\n\n# Create SDK instance\nfostrom = Fostrom({\n \"fleet_id\": \"<your-fleet-id>\",\n \"device_id\": \"<your-device-id>\",\n \"device_secret\": \"<your-device-secret>\",\n \"env\": \"<dev|test|prod>\",\n})\n\n# Setup mail handler for incoming messages\ndef handle_mail(mail: Mail):\n print(f\"Received: {mail.name} ({mail.id})\")\n mail.ack() # Acknowledge the message\n\nfostrom.on_mail = handle_mail\n\n# Start the Device Agent and event stream\nfostrom.start()\n\n# Send sensor data\nfostrom.send_datapoint(\"sensors\", {\n \"temperature\": 23.5,\n \"humidity\": 65,\n})\n\n# Send status messages\nfostrom.send_msg(\"status\", {\"online\": True})\n```\n\n## API Reference\n\n### Fostrom Class\n\n#### `__init__(config)`\nCreate a new Fostrom instance.\n\n**Parameters:**\n- `config` (dict): Configuration dictionary with:\n - `fleet_id` (str): Your fleet ID\n - `device_id` (str): Your device ID\n - `device_secret` (str): Your device secret\n - `log` (bool, default: True): Enable logging (default: True)\n - `env` (str, default: PYTHON_ENV || \"dev\"): Runtime Environment\n - `stop_agent_on_exit` (bool, default: False): If True, `shutdown()` will stop the Device Agent too.\n\n#### `start() -> None`\nStart the Device Agent in the background and connect to it.\n\n#### `shutdown(stop_agent: bool = False) -> None`\nStop the background event processing. If `stop_agent=True`, also stops the Device Agent.\n\n#### `send_datapoint(name: str, payload: dict) -> None`\nSend a datapoint to Fostrom.\n\n#### `send_msg(name: str, payload: dict | None) -> None`\nSend a message to Fostrom. Pass `None` if the schema has no payload.\n\n#### `mailbox_status() -> dict`\nGet current mailbox status.\n\n#### `next_mail() -> Mail | None`\nGet the next mail from the mailbox.\n\n\n### Mail Class\n\n#### Properties\n- `id` (str): Mail ID\n- `name` (str): Mail name/type\n- `payload` (dict): Mail payload data\n- `mailbox_size` (int): Current mailbox size\n\n#### Methods\n- `ack()`: Acknowledge the mail\n- `reject()`: Reject the mail\n- `requeue()`: Requeue the mail\n\n## Device Agent\n\nThe Fostrom Device SDK downloads and runs the Fostrom Device Agent in the background. The Device Agent is downloaded automatically when the package is installed. The Device Agent starts when `fostrom.start()` is called and handles all communication with the Fostrom platform. The Device Agent runs continuously in the background, even after your Python program has terminated, to ensure that when your process manager restarts your Python program, it connects to the Device Agent right away. In case you want to stop the Device Agent when your program terminates, you can pass `stop_agent_on_exit: True` to the config.\n\n## Logging\n\nThe SDK logs via Python's `logging` module using the `fostrom` logger. By default, WARNING/ERROR/CRITICAL are visible; INFO is not.\n\nTo see INFO messages (e.g., \"Connected\"), enable logging:\n\n```python\nimport logging\n\nlogging.basicConfig(level=logging.INFO)\n```\n\n## Links\n\n- **Fostrom Platform**: [https://fostrom.io](https://fostrom.io)\n- **Documentation**: [https://docs.fostrom.io/sdk/py](https://docs.fostrom.io/sdk/py)\n- **Python SDK**: [https://pypi.org/project/fostrom/](https://pypi.org/project/fostrom/)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Fostrom Device SDK",
"version": "0.0.14",
"project_urls": {
"Fostrom": "https://fostrom.io",
"SDK Docs": "https://docs.fostrom.io/sdk/py"
},
"split_keywords": [
"actions",
" cloud",
" datapoint",
" device",
" fleet",
" fostrom",
" hardware",
" iot",
" message",
" mqtt",
" raspberry",
" sdk",
" websockets"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "56a888ba634c55fe904691a5f541cf0dbb5c355795c0ddb745d7f2c778674cb5",
"md5": "b6b2426dca6064b3cd522e6b8cb44c2e",
"sha256": "16d38d50807b622effc020b89b364365b8dd0c2a8a4d0d1b350a6cac3f8e4152"
},
"downloads": -1,
"filename": "fostrom-0.0.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b6b2426dca6064b3cd522e6b8cb44c2e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 17286,
"upload_time": "2025-11-02T06:14:25",
"upload_time_iso_8601": "2025-11-02T06:14:25.802740Z",
"url": "https://files.pythonhosted.org/packages/56/a8/88ba634c55fe904691a5f541cf0dbb5c355795c0ddb745d7f2c778674cb5/fostrom-0.0.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a900e5b6a9062cd52ace758689c4011b4115a5b86c21d93be224fa62ce13fddf",
"md5": "510f158e3f5c52dc27012efcd311da76",
"sha256": "89b4fafcbef09f6dd38d3394ee22c0caf3255eaaf46e6a68d70937f52307553e"
},
"downloads": -1,
"filename": "fostrom-0.0.14.tar.gz",
"has_sig": false,
"md5_digest": "510f158e3f5c52dc27012efcd311da76",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 14199,
"upload_time": "2025-11-02T06:14:27",
"upload_time_iso_8601": "2025-11-02T06:14:27.553728Z",
"url": "https://files.pythonhosted.org/packages/a9/00/e5b6a9062cd52ace758689c4011b4115a5b86c21d93be224fa62ce13fddf/fostrom-0.0.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-02 06:14:27",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "fostrom"
}
JSON