Light Controller V2.2

A flexible Arduino-based light control system with native pulsing support, pattern compression, automatic calibration management, precise timing control, and pulse frequency modulation.

Version: 2.2.2
Last Updated: December 12, 2025
Status: Production Ready ✅

📑 Table of Contents

What's New in v2.2 - Latest features including automatic calibration
Quick Start - Get running in 10 minutes
Key Features - What it can do
Examples - Ready-to-use protocols (automatic vs preset calibration)
Documentation Index - 50+ organized guides
Protocol File Format - Syntax reference
Project Structure - File organization
Need Help? - Support resources

🎯 What's New in v2.2

✨ Automatic Calibration System (NEW!)

🤖 Board identification - Unique ID per Arduino (serial number/VID:PID)
💾 Database storage - Calibrations saved to calibration_database.json
♻️ Auto-retrieval - Stored calibrations automatically loaded
⏰ 3-month expiration - Auto-recalibration every 90 days for accuracy
🔧 Multi-board support - Different calibrations for different boards
📊 Database management - View, export, delete calibrations

Why 3 months? Crystal oscillators drift ±1-5 ppm/year. Over 3 months, this accumulates to 0.25-1.25 ppm drift, potentially causing 1-4 seconds error over 12-hour protocols. Regular recalibration ensures <1 second timing accuracy.

📖 Automatic Calibration Guide - Complete system documentation
📖 Backward Compatibility - How old protocols still work

Pattern-Based Compression System

Automatic pattern detection - Reduces hundreds of commands to just a few
Compression ratios up to 37:1 - 97%+ reduction in transmitted data
pattern_length parameter - Optimize for 2-element (default) or 4-element patterns
Efficiency analysis - System recommends optimal pattern_length

📖 Pattern Compression Guide - Complete compression details

Automatic Verification

Arduino compatibility checking - Prevents pattern_length mismatches
Early error detection - Catches issues before execution
Clear error messages - Tells you exactly how to fix problems

Enhanced Architecture

Class-based design - LightControllerParser class for reusability
70% smaller entry point - protocol_parser.py now just 49 lines
Command preview - Test protocols without hardware

📖 Refactoring Guide - Architecture details

🚀 Quick Start

1. Installation

# Clone repository
git clone https://github.com/Swida-Alba/light_controller_v2.git
cd light_controller_v2.2

# Install Python dependencies
pip install -r requirements.txt

📖 Full Installation Guide - Detailed setup instructions

2. Upload Arduino Firmware

Open light_controller_v2_2_arduino/light_controller_v2_2_arduino.ino in Arduino IDE

Configure settings (if needed):

const int PATTERN_LENGTH = 2;     // 2, 4, 8, etc. (must match Python)
#define PULSE_MODE_COMPILE 1      // 1=Enable pulses, 0=Disable (saves ~2.5KB)

Select your board: Tools → Board → Arduino Uno/Due/Mega
Select port: Tools → Port → (your Arduino port)
Click Upload

📖 Arduino Setup Guide - Board-specific instructions
📖 Firmware Update Guide - Updating existing firmware

3. Run Your First Protocol

Option A: Try Automatic Calibration (Recommended)

python protocol_parser.py 2 /dev/cu.usbmodem14301 examples/auto_calibration/simple_blink_example.txt

First time:

Identifying Arduino board...
Board ID: 0852420f343bb48d
No calibration found. Calibrate now? (Y/n): y
[Calibration proceeds for ~5 minutes]
✓ Calibration saved: 1.025847

Future runs:

✓ Found calibration: 1.025847
Age: 15 days (0.5 months) - Valid ✓
[Uses stored calibration automatically]

Option B: Use Preset Calibration (Legacy)

python protocol_parser.py 2 /dev/cu.usbmodem14301 examples/preset_calibration/simple_blink_example.txt

Shows warning about manual CALIBRATION_FACTOR, but still works!

📖 Usage Guide - Complete usage instructions
📖 Examples Guide - All example protocols explained

4. View Real-Time Monitoring (Automatic!)

After execution starts, an interactive HTML visualization automatically opens showing:

🔴 Real-time status updates every second
💡 LED indicators (ON/OFF/PULSING/WAITING/COMPLETED)
📊 Timeline view with current position marker
⏱️ Time tracking (upload time, total elapsed, protocol elapsed per channel)

📖 HTML Visualization Guide - Complete visualization features

5. Manage Calibrations

# View all calibrations with age and expiration status
python utils/manage_calibrations.py list

# Test board identification
python test_board_info.py

# Export calibrations
python utils/manage_calibrations.py export backup.txt

# Delete specific calibration
python utils/manage_calibrations.py delete <board_id>

📖 Database Management - Complete calibration system guide

🔑 Key Features

Calibration & Timing

✅ Automatic calibration - 🆕 Board-specific with 90-day expiration
✅ Multi-board support - 🆕 Different calibrations per Arduino
✅ Precise timing - Compensates for crystal oscillator variations
✅ Flexible timing - Milliseconds to hours
✅ Start time scheduling - Time-of-day or countdown

Pattern & Compression

✅ Pattern compression - Up to 97% reduction in command count
✅ Automatic verification - Arduino compatibility checking
✅ Efficiency analysis - Optimal pattern_length recommendations

Control & Monitoring

✅ Multi-channel control - Up to 8 channels
✅ Native pulsing support - Hardware PWM for frequency and duty cycle modulation
✅ Real-time visualization - 🎨 Interactive HTML with live status tracking
✅ Auto-generated timelines - Visual protocol representation

Protocols & Formats

✅ Multiple formats - Excel and Text protocols
✅ Command preview - Test without hardware
✅ Flexible protocols - 🆕 Automatic or preset calibration

📖 Features Overview - Complete feature list with examples

📂 Examples

The examples/ folder contains ready-to-use protocol files demonstrating both calibration approaches:

🆕 Auto-Calibration Examples (Recommended)

Located in examples/auto_calibration/ - Uses automatic calibration system:

File	Format	Description	Pattern Length
`simple_blink_example.txt`	TXT	Basic ON/OFF patterns	2
`simple_blink_example.xlsx`	Excel	Same as TXT (no calibration sheet)	2
`pulse_protocol.txt`	TXT	Multi-channel pulsed patterns	4
`pulse_protocol.xlsx`	Excel	Same as TXT	4
`multi_channel_pattern.txt`	TXT	Complex 4-element patterns	4
`multi_channel_pattern.xlsx`	Excel	Same as TXT	4

Key Feature: No CALIBRATION_FACTOR (TXT) or no calibration sheet (Excel) = automatic calibration enabled!

📖 Auto-Calibration Examples Guide

🔧 Preset Calibration Examples (Legacy)

Located in examples/preset_calibration/ - Uses manual CALIBRATION_FACTOR:

File	Format	Description	Pattern Length
`basic_protocol.txt/.xlsx`	Both	Simple channel control	4
`simple_blink_example.txt/.xlsx`	Both	ON/OFF blink patterns	2
`pulse_protocol.txt/.xlsx`	Both	Various pulsing effects	4
`wait_pulse_protocol.txt/.xlsx`	Both	Wait status with pulse	4
`pattern_length_4_example.txt/.xlsx`	Both	Complex 4-element patterns	4
`test_8_channels_pattern_length_4.txt`	TXT	All 8 channels	4

Contains: Manual CALIBRATION_FACTOR: 1.000000 in each protocol

⚠️ Important: Calibration factors are board-specific! Each Arduino has unique crystal oscillator characteristics. Using the wrong calibration factor can cause significant timing drift.

📖 Preset Calibration Examples Guide - Includes board-specific calibration explanation

📁 Root Examples

Additional examples in examples/ root:

clean_protocol.txt - Minimal template without comments
complete_protocol.txt - Fully documented with all features

📖 Complete Examples Guide - All examples explained
📖 Quick Reference - Fast example lookup

📚 Documentation Index

📖 Complete Documentation Index & Navigation Guide
Comprehensive guide to all 50+ documentation files organized by topic, user journey, and task.

Quick Navigation by Task

New Users:
Installation → Arduino Setup → Usage Guide → Examples

Create Protocol:
Protocol Formats → Templates → Examples

Optimize Performance:
Pattern Compression → Verification

Calibration:
Auto-Calibration Guide → Backward Compatibility → Calibration Methods

Troubleshoot:
Troubleshooting → Common Issues

Develop:
Refactoring Guide → Folder Structure

📑 Expand Full Documentation Categories

🚀 Getting Started

Installation Guide - Complete setup
Arduino Setup - Hardware configuration
Usage Guide - Basic and advanced usage
Quick Start Examples - Ready-to-use protocols

⏱️ Calibration System (NEW!)

Automatic Calibration Database - Complete system guide
Backward Compatibility - How old protocols work
Calibration Guide - Understanding timing calibration
Calibration Methods - V1, V1.1, V2 comparison
Calibration Quick Reference - Quick lookup

📖 Core Documentation

Features Overview - Complete feature list
Protocol Formats - Excel & Text specifications
Protocol Settings - Configuration parameters
Templates - Ready-to-use templates
Troubleshooting - Common issues

🎯 Pattern Compression

Pattern Compression Guide - How it works
Pattern Length Verification - Compatibility checking
Pattern Length Implementation - Technical details

🎨 Visualization & Monitoring

HTML Visualization - Real-time monitoring
Visualization Guide - Complete features
Command Preview - Test without hardware

💾 Memory & Pulse Mode

Compile-Time Pulse Memory - Pulse configuration
Pulse Period vs Section Time - ⚠️ IMPORTANT
Memory Reporting - Usage and compatibility

🏗️ Architecture & Development

Refactoring Guide - Class-based architecture
Folder Structure - Project organization
Build Instructions - Creating executables
Utility Scripts - Development tools

📄 Protocol File Format

Supported Formats:

Text (.txt) - Version control friendly, command syntax
Excel (.xlsx) - Visual editing with spreadsheet interface

Calibration Options

Automatic Calibration (Recommended):

# TXT: Simply omit CALIBRATION_FACTOR line
PATTERN:1;CH:1;STATUS:1,0;TIME_MS:1000,1000;REPEATS:10
START_TIME: {'CH1': 0}

# Excel: Omit 'calibration' sheet
# System automatically identifies Arduino and applies stored calibration

Preset Calibration (Legacy):

# TXT: Include CALIBRATION_FACTOR
PATTERN:1;CH:1;STATUS:1,0;TIME_MS:1000,1000;REPEATS:10
START_TIME: {'CH1': 0}
CALIBRATION_FACTOR: 1.025847  # Board-specific value!

# Excel: Include 'calibration' sheet with factor

⚠️ Important: Calibration factors are board-specific. Each Arduino has unique crystal oscillator characteristics due to manufacturing tolerances, temperature effects, and component aging. Never copy calibration factors between different boards!

Text Format (.txt)

Required Parameters

PATTERN commands (at least one per channel):

PATTERN:<id>;CH:<channel>;STATUS:<states>;TIME_MS:<durations>;REPEATS:<count>;PULSE:<optional>

START_TIME (for all channels):

START_TIME: {'CH1': '21:00', 'CH2': 60, 'CH3': '2025-11-08 21:00:00'}

Optional Parameters

WAIT_STATUS, WAIT_PULSE, CALIBRATION_FACTOR (see docs for details)

📖 Complete Protocol Syntax
📖 Protocol Settings Guide
📖 Templates

📁 Project Structure

light_controller_v2.2/
├── protocol_parser.py           # Main execution script
├── preview_protocol.py          # Preview without Arduino
├── viz_protocol_html.py         # HTML visualization generator
├── light_controller_parser.py   # Core parser class
├── lcfunc.py                    # Utility functions
├── test_board_info.py           # 🆕 Arduino board identification test
├── calibration_database.json    # 🆕 Stored calibrations (auto-generated)
├── requirements.txt             # Python dependencies
├── README.md                    # This file
├── CHANGELOG.md                 # Version history
│
├── examples/                    # Example protocol files
│   ├── auto_calibration/        # 🆕 Automatic calibration examples
│   │   ├── README.md            # Auto-calibration guide
│   │   ├── simple_blink_example.txt/.xlsx
│   │   ├── pulse_protocol.txt/.xlsx
│   │   ├── multi_channel_pattern.txt/.xlsx
│   │   └── create_excel_examples.py  # Script to generate Excel examples
│   │
│   ├── preset_calibration/      # 🆕 Manual calibration examples (legacy)
│   │   ├── README.md            # Preset calibration guide
│   │   ├── simple_blink_example.txt/.xlsx
│   │   ├── pulse_protocol.txt/.xlsx
│   │   ├── basic_protocol.txt/.xlsx
│   │   ├── wait_pulse_protocol.txt/.xlsx
│   │   └── ... (more examples)
│   │
│   ├── README.md                # Complete examples guide
│   ├── QUICK_REFERENCE.md       # Quick lookup
│   ├── clean_protocol.txt       # Minimal template
│   └── complete_protocol.txt    # Fully documented example
│
├── docs/                        # Documentation (50+ guides)
│   ├── DOCUMENTATION_INDEX.md   # 📖 Complete navigation guide
│   ├── AUTO_CALIBRATION_DATABASE.md  # 🆕 Calibration system
│   ├── BACKWARD_COMPATIBILITY.md     # 🆕 Legacy protocol support
│   ├── PATTERN_COMPRESSION_GUIDE.md  # Optimization
│   ├── HTML_VISUALIZATION.md    # Real-time monitoring
│   └── ... (40+ more guides)
│
├── utils/                       # Utility & development tools
│   ├── manage_calibrations.py   # 🆕 Calibration database manager
│   ├── debug_calibration_speed_test.py
│   ├── verify_pattern_length_fix.py
│   └── README.md
│
└── light_controller_v2_2_arduino/ # Arduino firmware
    └── light_controller_v2_2_arduino.ino

🆕 New in v2.2.1:

calibration_database.json - Auto-generated calibration storage
examples/auto_calibration/ - Automatic calibration examples
examples/preset_calibration/ - Legacy manual calibration examples
test_board_info.py - Arduino identification testing
utils/manage_calibrations.py - Database management utility
docs/AUTO_CALIBRATION_DATABASE.md - Complete calibration guide
docs/BACKWARD_COMPATIBILITY.md - Legacy protocol compatibility

🆘 Need Help?

Quick Links by Topic

Topic	Documentation
Setup	Installation → Arduino Setup
Calibration	Auto-Calibration → Backward Compatibility
Creating Protocols	Protocol Formats → Templates → Examples
Optimization	Pattern Compression → Verification
Timing Issues	Calibration Guide → Calibration Methods
Pulse Control	Pulse Period vs Section Time → Pulse Memory
Visualization	HTML Visualization → Realtime Features
Development	Refactoring Guide → Folder Structure
Troubleshooting	Troubleshooting Guide → Common Bugs

Support Resources

📖 Documentation Index - Complete navigation to all 50+ guides
📁 Documentation Folder - Browse all guides by category
🐛 GitHub Issues - Report bugs or request features
💡 Examples - Ready-to-use protocol templates
🔧 Troubleshooting - Common issues and solutions

📊 Project Status

Version: 2.2.2
Status: Production Ready ✅
Tested: Python 3.6-3.13, Arduino Uno/Due/Mega
License: MIT

Version History

v2.2.2 (Dec 12, 2025) - Improved serial communication reliability for PULSE commands, fixed calibration skip issue
v2.2.1 (Nov 10, 2025) - Automatic calibration system with 3-month expiration, examples reorganization
v2.2.0 (Nov 8, 2025) - Pattern compression, auto-verification, real-time visualization
v2.1.0 (Nov 3, 2025) - Text protocol support, multiple time units
v2.0.0 - Initial release

📖 Complete Changelog

🤝 Contributing

Contributions are welcome! Please:

Read the Documentation Index
Review Folder Structure
Understand Refactoring Guide
Submit pull requests with clear descriptions

🙏 Acknowledgments

Built with:

Python - Protocol parsing and serial communication
Arduino - Hardware control
NumPy - Data processing
Pandas - Protocol parsing (Excel)
PySerial - Serial communication
openpyxl - Excel file handling

Happy light controlling! 💡

Need calibration help? See Automatic Calibration Guide
Want to understand why calibration factors are board-specific? See Preset Calibration Examples

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
.pyinstaller_hooks		.pyinstaller_hooks
.vscode		.vscode
docs		docs
examples		examples
light_controller_v2_2_arduino		light_controller_v2_2_arduino
utils		utils
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
create_exe.py		create_exe.py
lcfunc.py		lcfunc.py
light_controller_parser.py		light_controller_parser.py
preview_protocol.py		preview_protocol.py
protocol_parser.py		protocol_parser.py
requirements.txt		requirements.txt
setup.py		setup.py
viz_protocol_html.py		viz_protocol_html.py

License

Swida-Alba/light_controller_v2

Folders and files

Latest commit

History

Repository files navigation