circuitnotion 1.2.0

IoT library for Raspberry Pi integration with CircuitNotion

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

Basic Installation

pip install circuitnotion

With GPIO Support

pip install circuitnotion[gpio]

With Sensor Support (Adafruit sensors)

pip install circuitnotion[sensors]

Full Installation

pip install circuitnotion[gpio,sensors]

Quick Start

import asyncio
from circuitnotion import CN, SensorValue

# Initialize
CN.begin(
    host="your-server.com",
    port=443,
    path="/ws",
    api_key="your-api-key-here",
    microcontroller_name="RaspberryPi-01"
)

# Map a device (relay on GPIO 17)
CN.map_digital_device("GT-001", 17, "Living Room Light")

# Add a temperature sensor
def read_temp():
    # Your sensor reading code here
    return SensorValue(25.5, "°C")

CN.add_temperature_sensor("TEMP-001", "Living Room", 5.0, read_temp)

# Run
asyncio.run(CN.run())

Examples

DHT22 Temperature & Humidity Sensor

import asyncio
import board
import adafruit_dht
from circuitnotion import CN, SensorValue

dht_device = adafruit_dht.DHT22(board.D4, use_pulseio=False)

def read_temperature():
    try:
        temp = dht_device.temperature
        return SensorValue(temp, "°C")
    except RuntimeError:
        return SensorValue(0.0, "°C")

def read_humidity():
    try:
        humidity = dht_device.humidity
        return SensorValue(humidity, "%")
    except RuntimeError:
        return SensorValue(0.0, "%")

async def main():
    CN.begin("server.com", 443, "/ws", "api-key", "Kitchen-Pi")
    
    # Add sensors (read every 5 seconds)
    CN.add_temperature_sensor("DHT22-T", "Kitchen", 5.0, read_temperature)
    CN.add_humidity_sensor("DHT22-H", "Kitchen", 5.0, read_humidity)
    
    # Map relay
    CN.map_digital_device("LIGHT-001", 17, "Kitchen Light")
    
    await CN.run()

asyncio.run(main())

DS18B20 Temperature Sensor (1-Wire)

import asyncio
import glob
from circuitnotion import CN, SensorValue

# Find DS18B20 sensor
device_file = glob.glob('/sys/bus/w1/devices/28*/w1_slave')[0]

def read_temperature():
    with open(device_file, 'r') as f:
        lines = f.readlines()
        temp_pos = lines[1].find('t=')
        temp_c = float(lines[1][temp_pos+2:]) / 1000.0
    return SensorValue(temp_c, "°C")

async def main():
    CN.begin("server.com", 443, "/ws", "api-key", "Garage-Pi")
    CN.add_temperature_sensor("DS18B20", "Garage", 10.0, read_temperature)
    await CN.run()

asyncio.run(main())

PIR Motion Sensor

import asyncio
import RPi.GPIO as GPIO
from circuitnotion import CN, SensorValue

PIR_PIN = 23
motion_detected = False

def pir_callback(channel):
    global motion_detected
    motion_detected = True

def read_motion():
    global motion_detected
    value = 1.0 if motion_detected else 0.0
    motion_detected = False
    return SensorValue(value, "boolean")

async def main():
    GPIO.setmode(GPIO.BCM)
    GPIO.setup(PIR_PIN, GPIO.IN)
    GPIO.add_event_detect(PIR_PIN, GPIO.RISING, callback=pir_callback)
    
    CN.begin("server.com", 443, "/ws", "api-key", "Entrance-Pi")
    CN.add_motion_sensor("PIR-001", "Front Door", 2.0, read_motion)
    
    try:
        await CN.run()
    finally:
        GPIO.cleanup()

asyncio.run(main())

API Reference

Initialization

CN.begin(host, port, path, api_key, microcontroller_name, use_ssl=True)

Device Mapping

# Digital device (relay, LED, etc.)
CN.map_digital_device(device_serial, pin, device_name, inverted=False)

# Analog/PWM device
CN.map_analog_device(device_serial, pin, device_name)

Sensors

# Add sensors
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)

# Manage sensors
CN.enable_sensor(sensor_type, device_serial)
CN.disable_sensor(sensor_type, device_serial)
CN.remove_all_sensors()

Callbacks

# Device control callback
def on_device_control(device_serial: str, state: str):
    print(f"Device {device_serial} -> {state}")

CN.on_device_control(on_device_control)

# Connection callback
def on_connection(connected: bool):
    print(f"Connected: {connected}")

CN.on_connection(on_connection)

# Custom logging
def on_log(message: str):
    print(f"LOG: {message}")

CN.on_log(on_log)

SensorValue

from circuitnotion import SensorValue

# Simple value
value = SensorValue(25.5, "°C")

# With metadata
value = SensorValue(25.5, "°C", metadata={"location": "outdoor"})

Hardware Setup

Enable 1-Wire (for DS18B20)

# Edit /boot/config.txt
sudo nano /boot/config.txt

# Add this line
dtoverlay=w1-gpio

# Reboot
sudo reboot

GPIO Pin Reference (BCM numbering)

• GPIO17 (Pin 11) - Common for relays
• GPIO27 (Pin 13)
• GPIO22 (Pin 15)
• GPIO4 (Pin 7) - Common for DHT sensors
• GPIO23 (Pin 16) - Common for PIR sensors

Requirements

• Python 3.7+
• Raspberry Pi (any model with GPIO)
• CircuitNotion account and API key

Supported Sensors

• DHT11/DHT22 (Temperature & Humidity)
• DS18B20 (1-Wire Temperature)
• PIR Motion Sensors
• Photoresistors (Light sensors)
• Any sensor with Python library support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 📖 Docs: Documentation

Changelog

1.0.0 (2026-02-08)

• Initial release
• WebSocket connection support
• GPIO device mapping
• Sensor reading and reporting
• Auto-reconnect functionality
• Examples for common sensors

Author

Your Name - GitHub

---

Made with ❤️ for IoT enthusiasts

## `LICENSE`

MIT License

Copyright (c) 2026 Your Name

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

## `MANIFEST.in`

include README.md include LICENSE include pyproject.toml include setup.cfg recursive-include examples *.py recursive-exclude * pycache recursive-exclude * *.py[co]

## `.gitignore`

Byte-compiled / optimized / DLL files

pycache/ *.py[cod] *$py.class

C extensions

*.so

Distribution / packaging

.Python build/ develop-eggs/ dist/ downloads/ eggs/ .eggs/ lib/ lib64/ parts/ sdist/ var/ wheels/ pip-wheel-metadata/ share/python-wheels/ *.egg-info/ .installed.cfg *.egg MANIFEST

PyInstaller

*.manifest *.spec

Unit test / coverage reports

htmlcov/ .tox/ .nox/ .coverage .coverage.* .cache nosetests.xml coverage.xml *.cover *.py,cover .hypothesis/ .pytest_cache/

Virtual environments

venv/ env/ ENV/ env.bak/ venv.bak/ .venv/

IDEs

.idea/ .vscode/ *.swp *.swo *~ .DS_Store

Project specific

*.log .env