update
This commit is contained in:
109
src/README.md
109
src/README.md
@@ -1,17 +1,17 @@
|
||||
# NATSBridge for Micropython
|
||||
# NATSBridge
|
||||
|
||||
A high-performance, bi-directional data bridge for Micropython devices using NATS (Core & JetStream), implementing the Claim-Check pattern for large payloads.
|
||||
A high-performance, bi-directional data bridge for **Julia**, **JavaScript**, and **Python/Micropython** using NATS (Core & JetStream), implementing the Claim-Check pattern for large payloads.
|
||||
|
||||
## Overview
|
||||
|
||||
This module provides functionality for sending and receiving data over NATS with automatic transport selection based on payload size:
|
||||
NATSBridge enables seamless communication between Julia, JavaScript, and Python/Micropython applications through NATS, with automatic transport selection based on payload size:
|
||||
|
||||
- **Direct Transport**: Payloads < 1MB are sent directly via NATS (Base64 encoded)
|
||||
- **Link Transport**: Payloads >= 1MB are uploaded to an HTTP file server and referenced via URL
|
||||
|
||||
## Features
|
||||
|
||||
- ✅ Bi-directional NATS communication
|
||||
- ✅ Bi-directional NATS communication across Julia ↔ JavaScript ↔ Python/Micropython
|
||||
- ✅ Multi-payload support (mixed content in single message)
|
||||
- ✅ Automatic transport selection based on payload size
|
||||
- ✅ File server integration for large payloads
|
||||
@@ -31,19 +31,56 @@ This module provides functionality for sending and receiving data over NATS with
|
||||
| `video` | Video data (MP4, AVI bytes) |
|
||||
| `binary` | Generic binary data |
|
||||
|
||||
## Implementation Guides
|
||||
|
||||
### [Julia Implementation](../tutorial_julia.md)
|
||||
|
||||
See the [Julia tutorial](../tutorial_julia.md) for getting started with Julia.
|
||||
|
||||
### [JavaScript Implementation](#javascript-implementation)
|
||||
|
||||
See [`NATSBridge.js`](NATSBridge.js) for the JavaScript implementation.
|
||||
|
||||
### [Python/Micropython Implementation](#pythonmicropython-implementation)
|
||||
|
||||
See [`nats_bridge.py`](nats_bridge.py) for the Python/Micropython implementation.
|
||||
|
||||
## Installation
|
||||
|
||||
1. Copy `nats_bridge.py` to your Micropython device
|
||||
### Julia
|
||||
|
||||
```julia
|
||||
using Pkg
|
||||
Pkg.add("NATS")
|
||||
Pkg.add("Arrow")
|
||||
Pkg.add("JSON3")
|
||||
Pkg.add("HTTP")
|
||||
Pkg.add("UUIDs")
|
||||
Pkg.add("Dates")
|
||||
```
|
||||
|
||||
### JavaScript
|
||||
|
||||
```bash
|
||||
npm install nats.js apache-arrow uuid base64-url
|
||||
```
|
||||
|
||||
### Python/Micropython
|
||||
|
||||
1. Copy `nats_bridge.py` to your device
|
||||
2. Ensure you have the following dependencies:
|
||||
- `urequests` for HTTP requests
|
||||
- `ubinascii` for base64 encoding
|
||||
- `ujson` for JSON handling
|
||||
- `usocket` for networking
|
||||
- `urequests` for HTTP requests (Micropython)
|
||||
- `requests` for HTTP requests (Python)
|
||||
- `base64` for base64 encoding
|
||||
- `json` for JSON handling
|
||||
- `socket` for networking (Micropython)
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Text Message
|
||||
|
||||
#### Python/Micropython
|
||||
|
||||
```python
|
||||
from nats_bridge import smartsend, smartreceive
|
||||
|
||||
@@ -57,8 +94,39 @@ for dataname, data, type in payloads:
|
||||
print("Received {}: {}".format(dataname, data))
|
||||
```
|
||||
|
||||
#### Julia
|
||||
|
||||
```julia
|
||||
using NATSBridge
|
||||
|
||||
# Sender
|
||||
data = [("message", "Hello World", "text")]
|
||||
env = smartsend("/chat/room1", data, nats_url="nats://localhost:4222")
|
||||
|
||||
# Receiver
|
||||
envelope = smartreceive(msg, fileserverDownloadHandler)
|
||||
# envelope["payloads"] = [("message", "Hello World", "text"), ...]
|
||||
```
|
||||
|
||||
#### JavaScript
|
||||
|
||||
```javascript
|
||||
const { smartsend, smartreceive } = require('./src/NATSBridge');
|
||||
|
||||
// Sender
|
||||
await smartsend("/chat/room1", [
|
||||
{ dataname: "message", data: "Hello World", type: "text" }
|
||||
], { natsUrl: "nats://localhost:4222" });
|
||||
|
||||
// Receiver
|
||||
const envelope = await smartreceive(msg);
|
||||
// envelope.payloads = [{ dataname: "message", data: "Hello World", type: "text" }, ...]
|
||||
```
|
||||
|
||||
### Sending JSON Configuration
|
||||
|
||||
#### Python/Micropython
|
||||
|
||||
```python
|
||||
from nats_bridge import smartsend
|
||||
|
||||
@@ -74,6 +142,8 @@ env = smartsend("/device/config", data, nats_url="nats://localhost:4222")
|
||||
|
||||
### Mixed Content (Chat with Text + Image)
|
||||
|
||||
#### Python/Micropython
|
||||
|
||||
```python
|
||||
from nats_bridge import smartsend
|
||||
|
||||
@@ -89,6 +159,8 @@ env = smartsend("/chat/mixed", data, nats_url="nats://localhost:4222")
|
||||
|
||||
### Request-Response Pattern
|
||||
|
||||
#### Python/Micropython
|
||||
|
||||
```python
|
||||
from nats_bridge import smartsend
|
||||
|
||||
@@ -105,6 +177,8 @@ env = smartsend(
|
||||
|
||||
### Large Payloads (File Server)
|
||||
|
||||
#### Python/Micropython
|
||||
|
||||
```python
|
||||
from nats_bridge import smartsend
|
||||
|
||||
@@ -191,21 +265,30 @@ Represents a single payload within a message envelope.
|
||||
|
||||
## Examples
|
||||
|
||||
See `examples/micropython_example.py` for more detailed examples.
|
||||
See [`examples/micropython_example.py`](../examples/micropython_example.py) for more detailed examples.
|
||||
|
||||
## Testing
|
||||
|
||||
Run the test suite:
|
||||
|
||||
```bash
|
||||
# Python/Micropython
|
||||
python test/test_micropython_basic.py
|
||||
|
||||
# JavaScript
|
||||
node test/test_js_to_js_text_sender.js
|
||||
node test/test_js_to_js_text_receiver.js
|
||||
|
||||
# Julia
|
||||
julia test/test_julia_to_julia_text_sender.jl
|
||||
julia test/test_julia_to_julia_text_receiver.jl
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- Micropython with networking support
|
||||
- NATS server (nats.io)
|
||||
- HTTP file server (optional, for large payloads)
|
||||
- **Julia**: NATS server (nats.io), HTTP file server (optional)
|
||||
- **JavaScript**: NATS server (nats.io), HTTP file server (optional)
|
||||
- **Python/Micropython**: NATS server (nats.io), HTTP file server (optional)
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Reference in New Issue
Block a user