raksa 0.2.1

MicroPython client library for In-situ Analytics and WebSocket communication with FastAPI

Raksa 🛡️

Raksa (derived from Sanskrit/Indonesian word for Protector or Guardian) is a high-persistence, self-contained MicroPython library built for the Noc Lab TinyML ecosystem as part of the 'Tiny Chip, Big Brain' workshop. It serves as an end-to-end In-situ Analytics gateway, securing stable asynchronous telemetry data stream from edge devices (ESP32/RP2040) to a FastAPI cloud backend.

Leveraging native compiler execution (@micropython.native) for fast on-device inference and memory consolidations (gc.collect()), Raksa protects MicroPython devices from heap fragmentation during high-velocity TinyML operations.

---

Key Features

• 🔄 Persistent WebSockets: Pure python RFC 6455 client implementation utilizing raw asynchronous uasyncio streams without external footprint overhead.
• ⚡ High-Speed In-situ Analytics: Edge inference calculations optimized directly via @micropython.native decorators to ensure minimal loop latency.
• 🧹 Heap Consolidation: Garbage collection executed dynamically inside data sync cycles to prevent RAM fragmentation on constrained hardware.
• 🇮🇩 Nusantara Resiliency: Promotes self-reliance, stability, and secure data guardianship for resource-constrained edge-to-cloud architectures.

---

Installation

Via pip (CPython / Desktop Testing)

pip install raksa

Via mip (MicroPython on Device)

1. Using mpremote (Recommended)

Connect your microcontroller board to your pc via USB/Serial and run:

mpremote mip install github:Muhammad-Ikhwan-Fathulloh/Raksa

2. Directly in MicroPython REPL

Ensure your microcontroller board has an active Wi-Fi connection, then run:

import mip
mip.install("github:Muhammad-Ikhwan-Fathulloh/Raksa")

---

Minimalist Code Example (ESP32 / RP2040)

Below is an end-to-end usage code highlighting edge inference and data synchronization under 10 lines of functional code:

import uasyncio as asyncio
from raksa import RaksaClient

async def main():
    client = RaksaClient("ws://192.168.1.100:8000/ws/telemetry")
    model = ([[0.5, -0.2], [0.1, 0.9]], [0.1, 0.0]) # TinyML weights & biases
    inputs = [0.8, 1.5] # Raw sensor variables
    
    pred = client.infer(model, inputs)
    await client.sync({"model": "NocML_V1", "features": inputs, "prediction": pred})

asyncio.run(main())

---

Complete Examples & Machine Learning Features

Full production-ready examples are available under the examples/ folder, covering both hardware-specific scenarios and internal, Scikit-Learn-compatible Machine Learning algorithms:

Hardware-Connected Scenarios

File	Scenario	Sensors
main_edge.py	Quick-start minimalist (< 10 lines)	—
esp32_wifi_sensor.py	ADC analog sensor + 3-class classification	LDR / MQ-x / Potentiometer
esp32_dht_monitor.py	Temperature & humidity anomaly detection	DHT11 / DHT22

On-Device Machine Learning & TinyML

File	Algorithms Covered	API Classes
ml_preprocessing.py	Custom Data Scaling & Extensions	MinMaxScaler, StandardScaler, PolynomialFeatures
ml_classification.py	Optimized Classifiers	KNN, NaiveBayes, LogisticRegression, DecisionTreeClassifier
ml_clustering.py	Unsupervised Grouping / Fit	KMeans
ml_forecasting.py	Simple Time Series forecasting	LinearForecaster
ml_neural.py	Perceptron & Feedforward NN	Perceptron, TinyNeuralNetwork, Activation
ml_evaluation.py	Evaluation & Split Metrics	LabelEncoder, TrainTestSplit, ConfusionMatrix
ml_anomaly.py	Anomaly Detection & PCA	AnomalyDetector, PCA

---

Machine Learning Reference

Raksa bundles a highly optimized port of the NocML C++ library along with original advanced TinyML tools, utilizing @micropython.native compiled mathematical loops to secure lightning-fast predictions directly on MicroPython edge boards without external dependencies.

Preprocessing & Decomposition

• MinMaxScaler(dims, min_vals, max_vals): Rescales variables to a range [0.0 - 1.0].
• StandardScaler(dims, means, stddevs): Standardizes features using population mean and variance.
• PolynomialFeatures(degree): Expands input dimension using combinations with replacement.
• PCA(n_components): Principal Component Analysis for dimensionality reduction with fit(X, n_samples, dims) and transform(x).
• LabelEncoder(): Standard encoder for string labels to integer classes with fit(), encode(), and decode().

Neural Networks

• Activation: Collection of activation functions: sigmoid(x), relu(x), tanh(x), and softmax(x).
• Perceptron(dims, lr=0.01): Single-layer perceptron for binary classification with train(X, y) and predict(x).
• TinyNeuralNetwork(layer_sizes, lr=0.1): Feedforward neural network supporting arbitrary hidden layers and backpropagation train(X, y, epochs).

Classification, Clustering & Forecasting

• KNN(training_data, labels, num_samples, dims, k=3): Traditional classification using Euclidean distances.
• NaiveBayes(num_classes, dims, means, vars, priors): Gaussian probabilistic classification.
• LogisticRegression(dims, weights, bias): Fast binary classification with predict() and predict_proba().
• DecisionTreeClassifier(nodes, num_nodes): Node list traverse trees supporting dictionary, tuple, or custom node structures.
• KMeans(k, dims, centroids): Clusters features into centroids. Supports run(data, num_samples) for on-device fitting.
• LinearForecaster(): Computes simple linear regressive trends ($y=mx+c$) natively via fit(x, y) and forecastNext().

Validation & Evaluation

• AnomalyDetector(threshold=2.5): Z-score outlier detector with fit(X, n_samples, dims) and detect(x).
• TrainTestSplit.split(X, y, dims, test_ratio): Shuffles and splits tabular data into train/test sets using LCG.
• ConfusionMatrix.report(y_true, y_pred): Compares predictions and outputs accuracy, precision, recall, and F1 metrics.

---

Acknowledgments & Credits

The machine learning capabilities contained in Raksa are ported from the NocML C++ Library for Arduino, developed by Muhammad Ikhwan Fathulloh. Special credits go to the original creators for providing the foundation of these resource-constrained edge execution algorithms.

---

Licenses & Copyrights

Developed by Noc Lab for nurturing TinyML literacy on hardware developers. Licensed under the MIT License.