CN
CircuitNotion
HomeML ToolsIncutiAIAI Models
IoT Platform
API Platform
Incuti AI
Ruganzu agent
Company
HomeML ToolsIncutiAIAI Models
Login
IoT PlatformAPI PlatformIncuti AIRuganzu agent
Company

Company

  • About Us
  • Our Story
  • Careers
  • Contact Us

Products

  • IoT Platform
  • IoT Documentation
  • API Platform
  • Ruganzu Agent
  • API Platform
  • API Documentation
  • IncutiAI Chat
  • AI Models
  • ML Tools

Resources

  • Blog
  • FAQ
  • Jobs
  • Rwanda AI Companies
  • Security
  • Privacy Policy
  • Terms of Service

CircuitNotion © 2026

CircuitNotion Arduino Library

Connect ESP8266/ESP32 microcontrollers to the CircuitNotion IoT platform

View on GitHubOpen Dashboard

Table of Contents

  • Overview
  • Installation
  • Dashboard Setup
  • Quick Start
  • Device Mapping
  • Sensor Management
  • API Reference
  • Examples
  • Troubleshooting
  • Support & Links

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)

  1. Open Arduino IDE
  2. Go to Tools → Manage Libraries
  3. Search for “CircuitNotion”
  4. Click Install

Method 2: Manual Installation

  1. Download the library ZIP from GitHub
  2. In Arduino IDE: Sketch → Include Library → Add .ZIP Library
  3. 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

  1. Visit iot.circuitnotion.com
  2. Click “Sign Up” and fill in your details
  3. Verify your email address
  4. 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

  1. Navigate to “Microcontrollers” in dashboard
  2. Click “Add New Microcontroller”
  3. Set Name: “Home Sensor Hub”, Board Type: ESP8266/ESP32
  4. 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}
1

Setup WiFi

Configure your WiFi credentials and initialize the connection.

2

Configure Connection

Set up CircuitNotion server connection with your API key.

3

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

Temperature Sensor
Humidity Sensor
Light Sensor
Motion Sensor
Custom Sensor

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

Resources

CircuitNotion Dashboard
iot.circuitnotion.com
GitHub Repository
Source code, issues, releases

Get Help

Email Support
support@circuitnotion.com
Community Forum
Ask questions, share projects

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-gpio to /boot/config.txt and 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.

Start your IoT journey today!

Sign up at CircuitNotionDownload Library

This library is released under the MIT License. Made with love for the Arduino community.