Overview
CircuitNotion provides client libraries for Python (Raspberry Pi, Linux) and C/Arduino (ESP8266, ESP32). Both connect to the same CircuitNotion Gate server over WebSocket: authenticate with an API key, receive device control commands (on/off, servo angle, volume, mute), send sensor readings, and trigger email notifications.
Real-time Communication
WebSocket-based bidirectional communication with CircuitNotion servers for instant device control and data updates.
Dashboard Integration
Full integration with the CircuitNotion web dashboard for monitoring, control, and data visualization.
Device Control
Map dashboard devices to local pins for automatic control of lights, relays, servos, and more.
Production Ready
Comprehensive error handling, auto-reconnection, and memory-efficient design for reliable operation.
CircuitNotion Gate server
WebSocket: wss://<host>/api/ws. Default host: iot.circuitnotion.com, port 443. Authenticate with api_key and optional microcontroller_name. Device control uses device_serial, state, and optional data (e.g. angle 0–180, volume, muted).
Key Features
- Temperature, humidity, light, motion sensors
- Auto-reconnection with robust error handling
- Change detection to optimize bandwidth
- Memory efficient for microcontrollers
- SSL/TLS encrypted communication
- Easy integration with existing projects
Installation
Prerequisites: ESP8266 or ESP32 microcontroller with WiFi connection
Method 1: Arduino Library Manager (Recommended)
- Open Arduino IDE
- Go to
Tools → Manage Libraries - Search for “CircuitNotion”
- Click Install
Method 2: Manual Installation
- Download the library ZIP from GitHub
- In Arduino IDE:
Sketch → Include Library → Add .ZIP Library - Select the downloaded ZIP file
Required Dependencies
Install via Arduino Library Manager:
ArduinoJson6.xWebSockets(Links2004/arduinoWebSockets)
Dashboard Setup
Before coding, set up your devices and microcontrollers in the CircuitNotion dashboard at iot.circuitnotion.com
Step 1: Create Account
- Visit iot.circuitnotion.com
- Click “Sign Up” and fill in your details
- Verify your email address
- Complete profile setup and choose subscription plan
Step 2: Create Devices
Example Device Configuration:
Living Room Light
- Type: Light/LED
- Location: Living Room
- Serial: LIGHT_001
Temperature Sensor
- Type: Sensor
- Location: Living Room
- Serial: TEMP_001
Step 3: Configure Microcontroller
- Navigate to “Microcontrollers” in dashboard
- Click “Add New Microcontroller”
- Set Name: “Home Sensor Hub”, Board Type: ESP8266/ESP32
- Copy the API Key - you’ll need this for Arduino code
Quick Start Guide
Basic Setup Example
1#include <CircuitNotion.h>
2
3CircuitNotion CN;
4
5// WiFi credentials
6const char* ssid = "YourWiFiNetwork";
7const char* password = "YourWiFiPassword";
8
9void setup() {
10 Serial.begin(115200);
11 CN.setWiFi(ssid, password);
12 // Minimal: default host iot.circuitnotion.com, 443, /api/ws
13 CN.begin("your-api-key", "Home Sensor Hub");
14 CN.onDeviceControl([](String serial, String state, JsonObject data) {
15 if (!data.isNull() && data.containsKey("angle")) {
16 int angle = data["angle"].as<int>();
17 // e.g. servo.write(angle);
18 }
19 });
20 CN.connect();
21}
22
23void loop() {
24 CN.loop();
25 delay(100);
26}Setup WiFi
Configure your WiFi credentials and initialize the connection.
Configure Connection
Set up CircuitNotion server connection with your API key.
Connect & Loop
Establish connection and maintain it in the main loop.
Device Mapping
Map dashboard devices to local microcontroller pins for automatic control from the web dashboard.
Device Mapping Examples
1// Map dashboard devices to local pins
2// mapDevice(serial, pin, name, isDigital) — true = digital (relay/LED), false = analog/PWM
3CN.mapDevice("LIGHT_001", D2, "Living Room Light", true);
4CN.mapDevice("RELAY_001", D3, "Water Pump", true);
5CN.mapDevice("DIMMER_001", D5, "Dimmable Light", false);
6CN.mapDevice("SERVO_001", D6, "Window Servo", false);Digital (relays, lights)
mapDevice(serial, pin, name, true)isDigital = true for ON/OFF control
Analog/PWM (servos, dimmers)
mapDevice(serial, pin, name, false)isDigital = false for PWM/servo
Sensor Management (C)
Use addSensor(type, deviceSerial, location, intervalMs, readCallback). The library sends sensor_reading messages; the Gate server stores them and links them to the device and user.
addSensor examples
1// addSensor(type, deviceSerial, location, intervalMs, readCallback)
2CN.addSensor("temperature", "TEMP_001", "Kitchen", 30000, readTemperature);
3CN.addSensor("humidity", "HUM_001", "Kitchen", 15000, readHumidity);
4CN.addSensor("pressure", "PRESS_001", "Basement", 60000, readPressure);C/Arduino API Reference
| Method | Description |
|---|---|
| begin(apiKey, name) | Use default Gate server (recommended). |
| begin(host, port, path, apiKey, name, useSSL) | Custom server. |
| setWiFi(ssid, password) | Connect WiFi before connect(). |
| connect() / disconnect() | Start/stop WebSocket. |
| loop() | Call in loop(); handles ping, sensors, reconnect. |
| onDeviceControl(callback) | Callback(deviceSerial, state, data). Use data["angle"], data["volume"], data["muted"]. |
| mapDevice(serial, pin, name, isDigital) | Map device to GPIO (digital: relay/light; analog: PWM/servo). |
| addSensor(type, deviceSerial, location, intervalMs, readCallback) | Send sensor readings to Gate. |
| sendNotification(template, variables) | POST to /api/notify. sendNotification(template) for no variables. |
Examples
Complete Home Automation System
This example demonstrates a complete home automation setup with temperature/humidity monitoring and device control capabilities.
Home Automation Example
1#include <CircuitNotion.h>
2#include <DHT.h>
3
4CircuitNotion CN;
5#define DHT_PIN D4
6#define DHT_TYPE DHT22
7DHT dht(DHT_PIN, DHT_TYPE);
8
9void setup() {
10 Serial.begin(115200);
11 dht.begin();
12 CN.setWiFi("YourWiFi", "YourPassword");
13 CN.begin("your-api-key", "Smart Home Hub");
14 CN.mapDevice("LIGHT_001", D2, "Living Room Light", true);
15 CN.mapDevice("FAN_001", D3, "Ceiling Fan", true);
16 CN.addSensor("temperature", "TEMP_001", "Living Room", 30000, readTemp);
17 CN.addSensor("humidity", "HUM_001", "Living Room", 30000, readHumidity);
18 CN.onDeviceControl([](String serial, String state, JsonObject data) {
19 Serial.println("Device " + serial + " -> " + state);
20 });
21 CN.connect();
22}
23
24// readCallback must provide sensor value (implementation depends on library)
25void loop() {
26 CN.loop();
27 delay(100);
28}Smart Garden Monitoring
Monitor soil moisture and light levels while controlling irrigation systems remotely.
Smart Garden Example
1#include <CircuitNotion.h>
2
3CircuitNotion CN;
4#define SOIL_MOISTURE_PIN A0
5#define WATER_PUMP_PIN D1
6
7void setup() {
8 Serial.begin(115200);
9 CN.setWiFi("YourWiFi", "YourPassword");
10 CN.begin("your-api-key", "Smart Garden");
11 CN.mapDevice("PUMP_001", WATER_PUMP_PIN, "Water Pump", true);
12 CN.addSensor("soil_moisture", "SOIL_001", "Garden", 30000, readSoilMoisture);
13 CN.addSensor("light", "LIGHT_001", "Garden", 60000, readLightLevel);
14 CN.connect();
15}
16
17void loop() {
18 CN.loop();
19 delay(100);
20}Use Cases
Home Automation
Monitor temperature, humidity, and light levels while controlling lights and fans.
Smart Gardening
Track soil moisture, temperature, and automate watering systems.
Security Systems
Motion detection, door sensors, and automatic lighting control.
🏭 Industrial Monitoring
Machine temperature monitoring, production counters, and alert systems.
Troubleshooting
Cannot access iot.circuitnotion.com
- • Check your internet connection
- • Try clearing browser cache
- • Contact support if site is down
Device not appearing in dashboard
- • Verify device creation in dashboard
- • Check device serial matches Arduino code
- • Ensure microcontroller is connected
Arduino will not connect
- • Verify WiFi credentials
- • Check API key copied correctly from dashboard
- • Ensure microcontroller name matches dashboard
- • Monitor Serial output for error messages
Sensors not sending data
- • Verify device serials match dashboard
- • Check sensor hardware connections
- • Confirm sensor initialization in code
- • Test sensor readings independently
Memory or connection issues
- • Reduce sensor reading frequency (intervalMs)
- • Call
CN.loop()regularly; library handles ping and reconnect - • Monitor free heap with
ESP.getFreeHeap()
Support & Links
Resources
Security & Compliance
- • WSS (WebSocket Secure) encryption
- • API key authentication
- • SSL/TLS for all data transmission
- • Dashboard access control
- • User permissions management
- • Secure device registration
CircuitNotion Python Library
For Raspberry Pi and Linux. GitHub · pip install circuitnotion
Features
- WebSocket to CircuitNotion Gate with API key auth; minimal
begin(api_key, microcontroller_name) - Device control:
on_device_control(device_serial, state, data)— usedata["angle"](0–180) for servos - GPIO:
map_digital_device,map_analog_device - Sensors:
add_temperature_sensor,add_humidity_sensor,add_light_sensor,add_motion_sensor,add_sensor - Email:
send_notification(template, **variables)orSendNotification(host, api_key, template, ...)— templates:threshold_alert,device_alert,custom - Auto-reconnect, connection/log callbacks, diagnostics
Installation
Install via pip
1pip install circuitnotion
2pip install circuitnotion[gpio] # Raspberry Pi
3pip install circuitnotion[sensors] # e.g. Adafruit DHT
4pip install circuitnotion[gpio,sensors] # fullQuick Start
Python Quick Start
1import asyncio
2from circuitnotion import CN, SensorValue
3
4# Minimal: host = iot.circuitnotion.com, 443, /api/ws
5CN.begin("your-api-key-here", "RaspberryPi-01")
6CN.map_digital_device("GT-001", 17, "Living Room Light")
7
8def read_temp():
9 return SensorValue(25.5, "°C")
10
11CN.add_temperature_sensor("TEMP-001", "Living Room", 5.0, read_temp)
12asyncio.run(CN.run())Custom server: CN.begin(host, port, path, api_key, microcontroller_name, use_ssl=True)
API Reference (Python)
CN.begin(api_key, microcontroller_name)— minimalCN.begin(host, port, path, api_key, microcontroller_name, use_ssl=True)— fullmap_digital_device(serial, pin, name, inverted=False)·map_analog_device(serial, pin, name)on_device_control(callback)·control_local_device(serial, state, data=None)add_sensor(type, serial, location, interval, callback)·add_temperature_sensor,add_humidity_sensor,add_light_sensor,add_motion_sensorsend_notification(template, **variables)·SendNotification(host, api_key, template, ...)SensorValue(value, unit, metadata=None)
Changelog
- Python 1.3.0: Minimal begin(api_key, name); send_notification / SendNotification; device control (device_serial, state, data); control_local_device(..., data=None); disconnect, is_connected, get_status, get_uptime, print_diagnostics.
- Python 1.2.0: add_humidity_sensor, add_light_sensor, add_motion_sensor; map_analog_device; enable_sensor, disable_sensor, remove_all_sensors; auth_error handling.
- Python 1.0.0: Initial release (WebSocket, GPIO mapping, sensors, auto-reconnect).
- C 1.1.0: Minimal begin(apiKey, name); device control with data (angle, volume, muted); sendNotification(template, variables) using stored config.
Common concepts
Both libraries default to iot.circuitnotion.com, port 443, path /api/ws. Use minimal begin(apiKey, name) for quick setup. Email notifications: templates threshold_alert, device_alert, custom with variables (e.g. DeviceName, SensorType, Value, Unit, Threshold, Message).