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

#include <CircuitNotion.h>

// WiFi credentials
const char* ssid = "YourWiFiNetwork";
const char* password = "YourWiFiPassword";

// CircuitNotion configuration
const char* api_key = "your-microcontroller-api-key";
const char* microcontroller_name = "Home Sensor Hub";

void setup() {
  Serial.begin(115200);
  
  // Setup WiFi
  CN.setWiFi(ssid, password);
  
  // Configure CircuitNotion connection
  CN.begin("iot.circuitnotion.com", 443, "/ws", api_key, microcontroller_name);
  
  // Connect
  CN.connect();
}

void loop() {
  CN.loop();
  delay(100);
}

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

// Map dashboard devices to local pins
CN.mapDigitalDevice("LIGHT_001", D2, "Living Room Light");
CN.mapDigitalDevice("RELAY_001", D3, "Water Pump", true); // inverted logic
CN.mapAnalogDevice("DIMMER_001", D5, "Dimmable Light");
CN.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

// Temperature sensor reading every 30 seconds
CN.addTemperatureSensor("TEMP_001", "Kitchen", 30000, readTemperature);

// Humidity sensor with change detection
auto* humidity = CN.addHumiditySensor("HUM_001", "Kitchen", 15000, readHumidity);
humidity->setChangeThreshold(5.0); // Only send if changed by 5%
humidity->enableChangeDetection(true);

// Custom sensor
CN.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

#include <CircuitNotion.h>
#include <DHT.h>

// DHT sensor setup
#define DHT_PIN D4
#define DHT_TYPE DHT22
DHT dht(DHT_PIN, DHT_TYPE);

// WiFi and CircuitNotion config
const char* ssid = "YourWiFi";
const char* password = "YourPassword";
const char* api_key = "your-api-key";

void setup() {
  Serial.begin(115200);
  dht.begin();
  
  CN.setWiFi(ssid, password);
  CN.begin("iot.circuitnotion.com", 443, "/ws", api_key, "Smart Home Hub");
  
  // Device mappings
  CN.mapDigitalDevice("LIGHT_001", D2, "Living Room Light");
  CN.mapDigitalDevice("FAN_001", D3, "Ceiling Fan");
  
  // Sensors
  CN.addTemperatureSensor("TEMP_001", "Living Room", 30000, readTemp);
  CN.addHumiditySensor("HUM_001", "Living Room", 30000, readHumidity);
  
  // Callbacks
  CN.onDeviceControl([](String deviceSerial, String state) {
    Serial.println("Device " + deviceSerial + " -> " + state);
  });
  
  CN.connect();
}

SensorValue readTemp() {
  float temp = dht.readTemperature();
  return SensorValue(temp, "°C");
}

SensorValue readHumidity() {
  float humidity = dht.readHumidity();
  return SensorValue(humidity, "%");
}

void loop() {
  CN.loop();
  delay(100);
}

Smart Garden Monitoring

Monitor soil moisture and light levels while controlling irrigation systems remotely.

Smart Garden Example

#include <CircuitNotion.h>

// Pin definitions
#define SOIL_MOISTURE_PIN A0
#define WATER_PUMP_PIN D1
#define LIGHT_SENSOR_PIN A1

// Configuration
const char* ssid = "YourWiFi";
const char* password = "YourPassword";
const char* api_key = "your-api-key";

void setup() {
  Serial.begin(115200);
  
  CN.setWiFi(ssid, password);
  CN.begin("iot.circuitnotion.com", 443, "/ws", api_key, "Smart Garden");
  
  // Map water pump control
  CN.mapDigitalDevice("PUMP_001", WATER_PUMP_PIN, "Water Pump");
  
  // Add sensors
  CN.addCustomSensor("soil_moisture", "SOIL_001", "Garden", 30000, readSoilMoisture);
  CN.addLightSensor("LIGHT_001", "Garden", 60000, readLightLevel);
  
  CN.connect();
}

SensorValue readSoilMoisture() {
  int moisture = analogRead(SOIL_MOISTURE_PIN);
  float percentage = map(moisture, 0, 1024, 0, 100);
  return SensorValue(percentage, "%");
}

SensorValue readLightLevel() {
  int light = analogRead(LIGHT_SENSOR_PIN);
  float lux = map(light, 0, 1024, 0, 1000);
  return SensorValue(lux, "lux");
}

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

Overview

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

#include <CircuitNotion.h>

// WiFi credentials
const char* ssid = "YourWiFiNetwork";
const char* password = "YourWiFiPassword";

// CircuitNotion configuration
const char* api_key = "your-microcontroller-api-key";
const char* microcontroller_name = "Home Sensor Hub";

void setup() {
  Serial.begin(115200);
  
  // Setup WiFi
  CN.setWiFi(ssid, password);
  
  // Configure CircuitNotion connection
  CN.begin("iot.circuitnotion.com", 443, "/ws", api_key, microcontroller_name);
  
  // Connect
  CN.connect();
}

void loop() {
  CN.loop();
  delay(100);
}

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

// Map dashboard devices to local pins
CN.mapDigitalDevice("LIGHT_001", D2, "Living Room Light");
CN.mapDigitalDevice("RELAY_001", D3, "Water Pump", true); // inverted logic
CN.mapAnalogDevice("DIMMER_001", D5, "Dimmable Light");
CN.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

// Temperature sensor reading every 30 seconds
CN.addTemperatureSensor("TEMP_001", "Kitchen", 30000, readTemperature);

// Humidity sensor with change detection
auto* humidity = CN.addHumiditySensor("HUM_001", "Kitchen", 15000, readHumidity);
humidity->setChangeThreshold(5.0); // Only send if changed by 5%
humidity->enableChangeDetection(true);

// Custom sensor
CN.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

#include <CircuitNotion.h>
#include <DHT.h>

// DHT sensor setup
#define DHT_PIN D4
#define DHT_TYPE DHT22
DHT dht(DHT_PIN, DHT_TYPE);

// WiFi and CircuitNotion config
const char* ssid = "YourWiFi";
const char* password = "YourPassword";
const char* api_key = "your-api-key";

void setup() {
  Serial.begin(115200);
  dht.begin();
  
  CN.setWiFi(ssid, password);
  CN.begin("iot.circuitnotion.com", 443, "/ws", api_key, "Smart Home Hub");
  
  // Device mappings
  CN.mapDigitalDevice("LIGHT_001", D2, "Living Room Light");
  CN.mapDigitalDevice("FAN_001", D3, "Ceiling Fan");
  
  // Sensors
  CN.addTemperatureSensor("TEMP_001", "Living Room", 30000, readTemp);
  CN.addHumiditySensor("HUM_001", "Living Room", 30000, readHumidity);
  
  // Callbacks
  CN.onDeviceControl([](String deviceSerial, String state) {
    Serial.println("Device " + deviceSerial + " -> " + state);
  });
  
  CN.connect();
}

SensorValue readTemp() {
  float temp = dht.readTemperature();
  return SensorValue(temp, "°C");
}

SensorValue readHumidity() {
  float humidity = dht.readHumidity();
  return SensorValue(humidity, "%");
}

void loop() {
  CN.loop();
  delay(100);
}

Smart Garden Monitoring

Monitor soil moisture and light levels while controlling irrigation systems remotely.

Smart Garden Example

#include <CircuitNotion.h>

// Pin definitions
#define SOIL_MOISTURE_PIN A0
#define WATER_PUMP_PIN D1
#define LIGHT_SENSOR_PIN A1

// Configuration
const char* ssid = "YourWiFi";
const char* password = "YourPassword";
const char* api_key = "your-api-key";

void setup() {
  Serial.begin(115200);
  
  CN.setWiFi(ssid, password);
  CN.begin("iot.circuitnotion.com", 443, "/ws", api_key, "Smart Garden");
  
  // Map water pump control
  CN.mapDigitalDevice("PUMP_001", WATER_PUMP_PIN, "Water Pump");
  
  // Add sensors
  CN.addCustomSensor("soil_moisture", "SOIL_001", "Garden", 30000, readSoilMoisture);
  CN.addLightSensor("LIGHT_001", "Garden", 60000, readLightLevel);
  
  CN.connect();
}

SensorValue readSoilMoisture() {
  int moisture = analogRead(SOIL_MOISTURE_PIN);
  float percentage = map(moisture, 0, 1024, 0, 100);
  return SensorValue(percentage, "%");
}

SensorValue readLightLevel() {
  int light = analogRead(LIGHT_SENSOR_PIN);
  float lux = map(light, 0, 1024, 0, 1000);
  return SensorValue(lux, "lux");
}