Overview
CircuitNotion is a powerful Arduino library designed for ESP8266 and ESP32 microcontrollers. It provides seamless integration with the CircuitNotion IoT platform, enabling real-time sensor data collection, device control, and comprehensive dashboard management.
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.
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 these libraries via Arduino Library Manager:
ArduinoJson(6.21.3 or later)WebSocketsClient(2.3.7 or later)DHT sensor library(1.4.4 or later) - for temperature/humidity sensors
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
3// WiFi credentials
4const char* ssid = "YourWiFiNetwork";
5const char* password = "YourWiFiPassword";
6
7// CircuitNotion configuration
8const char* api_key = "your-microcontroller-api-key";
9const char* microcontroller_name = "Home Sensor Hub";
10
11void setup() {
12 Serial.begin(115200);
13
14 // Setup WiFi
15 CN.setWiFi(ssid, password);
16
17 // Configure CircuitNotion connection
18 CN.begin("iot.circuitnotion.com", 443, "/api/ws", api_key, microcontroller_name);
19
20 // Connect
21 CN.connect();
22}
23
24void loop() {
25 CN.loop();
26 delay(100);
27}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
2CN.mapDigitalDevice("LIGHT_001", D2, "Living Room Light");
3CN.mapDigitalDevice("RELAY_001", D3, "Water Pump", true); // inverted logic
4CN.mapAnalogDevice("DIMMER_001", D5, "Dimmable Light");
5CN.mapPWMDevice("SERVO_001", D6, "Window Servo");Digital Devices
mapDigitalDevice(deviceSerial, pin, name, inverted)For LEDs, relays, switches (ON/OFF control)
Analog/PWM Devices
mapAnalogDevice(deviceSerial, pin, name)For dimmers, variable controls
mapPWMDevice(deviceSerial, pin, name)For servos, motors with precise control
Sensor Management
Sensor Configuration Examples
1// Temperature sensor reading every 30 seconds
2CN.addTemperatureSensor("TEMP_001", "Kitchen", 30000, readTemperature);
3
4// Humidity sensor with change detection
5auto* humidity = CN.addHumiditySensor("HUM_001", "Kitchen", 15000, readHumidity);
6humidity->setChangeThreshold(5.0); // Only send if changed by 5%
7humidity->enableChangeDetection(true);
8
9// Custom sensor
10CN.addCustomSensor("pressure", "PRESS_001", "Basement", 60000, readPressure);Built-in Sensor Types
Optimization Features
Change Detection
Only send data when values change significantly
Configurable Intervals
Set custom reading frequencies per sensor
Dynamic Control
Enable/disable sensors at runtime
API Reference
Connection Methods
setWiFi(ssid, password)Configure WiFi credentials
connect() / disconnect()Manage connection state
bool isConnected() / bool isAuthenticated()Check connection status
Device Control Methods
mapDigitalDevice(deviceSerial, pin, name, inverted=false)Map digital device (LED, relay, etc.)
mapAnalogDevice(deviceSerial, pin, name)Map analog device (dimmer, etc.)
mapPWMDevice(deviceSerial, pin, name)Map PWM device (servo, motor, etc.)
controlLocalDevice(deviceSerial, state/value)Manually control mapped device
Sensor Methods
addTemperatureSensor(deviceSerial, location, interval, callback)Add temperature sensor with reading callback
addHumiditySensor(deviceSerial, location, interval, callback)Add humidity sensor with reading callback
addLightSensor(deviceSerial, location, interval, callback)Add light sensor with reading callback
addMotionSensor(deviceSerial, location, interval, callback)Add motion sensor with reading callback
addCustomSensor(type, deviceSerial, location, interval, callback)Add custom sensor with specified type
Callback Methods
onDeviceControl(callback)Handle device control commands from dashboard
onConnection(callback)Handle connection state changes
onLog(callback)Handle library log messages and diagnostics
Utility Methods
enableAutoReconnect(enabled, interval=5000)Enable automatic reconnection with custom interval
printDiagnostics() / printSensorStatus()Print comprehensive system diagnostics
getSensorCount() / getLibraryVersion()Get system statistics and version information
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
4// DHT sensor setup
5#define DHT_PIN D4
6#define DHT_TYPE DHT22
7DHT dht(DHT_PIN, DHT_TYPE);
8
9// WiFi and CircuitNotion config
10const char* ssid = "YourWiFi";
11const char* password = "YourPassword";
12const char* api_key = "your-api-key";
13
14void setup() {
15 Serial.begin(115200);
16 dht.begin();
17
18 CN.setWiFi(ssid, password);
19 CN.begin("iot.circuitnotion.com", 443, "/api/ws", api_key, "Smart Home Hub");
20
21 // Device mappings
22 CN.mapDigitalDevice("LIGHT_001", D2, "Living Room Light");
23 CN.mapDigitalDevice("FAN_001", D3, "Ceiling Fan");
24
25 // Sensors
26 CN.addTemperatureSensor("TEMP_001", "Living Room", 30000, readTemp);
27 CN.addHumiditySensor("HUM_001", "Living Room", 30000, readHumidity);
28
29 // Callbacks
30 CN.onDeviceControl([](String deviceSerial, String state) {
31 Serial.println("Device " + deviceSerial + " -> " + state);
32 });
33
34 CN.connect();
35}
36
37SensorValue readTemp() {
38 float temp = dht.readTemperature();
39 return SensorValue(temp, "°C");
40}
41
42SensorValue readHumidity() {
43 float humidity = dht.readHumidity();
44 return SensorValue(humidity, "% ");
45}
46
47void loop() {
48 CN.loop();
49 delay(100);
50}Smart Garden Monitoring
Monitor soil moisture and light levels while controlling irrigation systems remotely.
Smart Garden Example
1#include <CircuitNotion.h>
2
3// Pin definitions
4#define SOIL_MOISTURE_PIN A0
5#define WATER_PUMP_PIN D1
6#define LIGHT_SENSOR_PIN A1
7
8// Configuration
9const char* ssid = "YourWiFi";
10const char* password = "YourPassword";
11const char* api_key = "your-api-key";
12
13void setup() {
14 Serial.begin(115200);
15
16 CN.setWiFi(ssid, password);
17 CN.begin("iot.circuitnotion.com", 443, "/api/ws", api_key, "Smart Garden");
18
19 // Map water pump control
20 CN.mapDigitalDevice("PUMP_001", WATER_PUMP_PIN, "Water Pump");
21
22 // Add sensors
23 CN.addCustomSensor("soil_moisture", "SOIL_001", "Garden", 30000, readSoilMoisture);
24 CN.addLightSensor("LIGHT_001", "Garden", 60000, readLightLevel);
25
26 CN.connect();
27}
28
29SensorValue readSoilMoisture() {
30 int moisture = analogRead(SOIL_MOISTURE_PIN);
31 float percentage = map(moisture, 0, 1024, 0, 100);
32 return SensorValue(percentage, "% ");
33}
34
35SensorValue readLightLevel() {
36 int light = analogRead(LIGHT_SENSOR_PIN);
37 float lux = map(light, 0, 1024, 0, 1000);
38 return SensorValue(lux, "lux");
39}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
- • Enable change detection to reduce transmissions
- • Enable auto-reconnect:
CN.enableAutoReconnect(true) - • Monitor free heap with
ESP.getFreeHeap()
Support & Links
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
Python library for connecting Raspberry Pi to the CircuitNotion IoT platform. Control devices, read sensors, and build smart home automation with ease.
Features
- 🔌 WebSocket Connection: Real-time bidirectional communication
- 📊 Sensor Support: Temperature, humidity, motion, light, and custom sensors
- 🎛️ Device Control: Control GPIO pins remotely through CircuitNotion
- 🔄 Auto-reconnect: Automatic reconnection on connection loss
- 📡 Real-time Updates: Receive device control commands instantly
- 🔧 Easy Integration: Simple API for quick setup
Installation
Install via pip
1pip install circuitnotion
2pip install circuitnotion[gpio]
3pip install circuitnotion[sensors]
4pip install circuitnotion[gpio,sensors]Quick Start
Python Quick Start Example
1import asyncio
2from circuitnotion import CN, SensorValue
3
4# Initialize
5CN.begin(host="your-server.com", port=443, path="/api/ws", api_key="your-api-key-here", microcontroller_name="RaspberryPi-01")
6
7# Map a device (relay on GPIO 17)
8CN.map_digital_device("GT-001", 17, "Living Room Light")
9
10# Add a temperature sensor
11def read_temp():
12 return SensorValue(25.5, "°C")
13
14CN.add_temperature_sensor("TEMP-001", "Living Room", 5.0, read_temp)
15
16# Run
17asyncio.run(CN.run())Examples
DHT22 Temperature & Humidity Example
1# DHT22 Example
2import asyncio
3import board
4import adafruit_dht
5from circuitnotion import CN, SensorValue
6
7dht_device = adafruit_dht.DHT22(board.D4, use_pulseio=False)
8
9# ... (rest of the DHT22 example code) ...
10
11async def main():
12 CN.begin("server.com", 443, "/api/ws", "api-key", "Kitchen-Pi")
13 CN.add_temperature_sensor("DHT22-T", "Kitchen", 5.0, read_temperature)
14 CN.add_humidity_sensor("DHT22-H", "Kitchen", 5.0, read_humidity)
15 CN.map_digital_device("LIGHT-001", 17, "Kitchen Light")
16 await CN.run()
17
18asyncio.run(main())DS18B20 Temperature Example
1# DS18B20 Example
2import asyncio
3import glob
4from circuitnotion import CN, SensorValue
5
6device_file = glob.glob('/sys/bus/w1/devices/28*/w1_slave')[0]
7
8def read_temperature():
9 with open(device_file, 'r') as f:
10 lines = f.readlines()
11 temp_pos = lines[1].find('t=')
12 temp_c = float(lines[1][temp_pos+2:]) / 1000.0
13 return SensorValue(temp_c, "°C")
14
15async def main():
16 CN.begin("server.com", 443, "/api/ws", "api-key", "Garage-Pi")
17 CN.add_temperature_sensor("DS18B20", "Garage", 10.0, read_temperature)
18 await CN.run()
19
20asyncio.run(main())PIR Motion Sensor Example
1# PIR Motion Example
2import asyncio
3import RPi.GPIO as GPIO
4from circuitnotion import CN, SensorValue
5
6PIR_PIN = 23
7motion_detected = False
8
9def pir_callback(channel):
10 global motion_detected
11 motion_detected = True
12
13def read_motion():
14 global motion_detected
15 value = 1.0 if motion_detected else 0.0
16 motion_detected = False
17 return SensorValue(value, "boolean")
18
19async def main():
20 GPIO.setmode(GPIO.BCM)
21 GPIO.setup(PIR_PIN, GPIO.IN)
22 GPIO.add_event_detect(PIR_PIN, GPIO.RISING, callback=pir_callback)
23 CN.begin("server.com", 443, "/api/ws", "api-key", "Entrance-Pi")
24 CN.add_motion_sensor("PIR-001", "Front Door", 2.0, read_motion)
25 try:
26 await CN.run()
27 finally:
28 GPIO.cleanup()
29
30asyncio.run(main())Callback Examples
1# Device control callback
2def on_device_control(device_serial: str, state: str):
3 print(f"Device {device_serial} -> {state}")
4CN.on_device_control(on_device_control)
5
6# Connection callback
7def on_connection(connected: bool):
8 print(f"Connected: {connected}")
9CN.on_connection(on_connection)
10
11# Custom logging
12def on_log(message: str):
13 print(f"LOG: {message}")
14CN.on_log(on_log)SensorValue Example
1# SensorValue usage
2from circuitnotion import SensorValue
3value = SensorValue(25.5, "°C")
4value = SensorValue(25.5, "°C", metadata={"location": "outdoor"})API Reference
- CN.begin(host, port, path, api_key, microcontroller_name, use_ssl=True)
- CN.map_digital_device(device_serial, pin, device_name, inverted=False)
- CN.map_analog_device(device_serial, pin, device_name)
- CN.add_temperature_sensor(device_serial, location, interval, callback)
- CN.add_humidity_sensor(device_serial, location, interval, callback)
- CN.add_light_sensor(device_serial, location, interval, callback)
- CN.add_motion_sensor(device_serial, location, interval, callback)
- CN.add_sensor(sensor_type, device_serial, location, interval, callback)
- CN.enable_sensor(sensor_type, device_serial)
- CN.disable_sensor(sensor_type, device_serial)
- CN.remove_all_sensors()
- CN.on_device_control(callback)
- CN.on_connection(callback)
- CN.on_log(callback)
- SensorValue(value, unit, metadata=None)
Hardware Setup & Requirements
- Enable 1-Wire: Add
dtoverlay=w1-gpioto/boot/config.txtand reboot - GPIO Pin Reference: 17, 27, 22, 4, 23 (BCM numbering)
- Python 3.7+, Raspberry Pi (any model with GPIO), CircuitNotion account and API key
- Supported sensors: DHT11/DHT22, DS18B20, PIR, photoresistors, any sensor with Python library support
License & Support
- MIT License
- Support: support@circuitnotion.com
- GitHub Issues, Docs, Community Forum
Changelog
- 1.0.0 (2026-02-08): Initial release, WebSocket connection, GPIO device mapping, sensor reading/reporting, auto-reconnect, examples for common sensors
Author
Your Name - GitHub. Made with ❤️ for IoT enthusiasts.