Skip to main content

Overview

SerialCommander provides a full-featured command-line interface for AutoLight V3 with multi-level access control, WiFi management, LED control, PCF debugging, and system configuration.

Quick Start

#define ENABLE_ADDONS_AUTOLIGHT_V3
#include "Kinematrix.h"
using namespace AutoLight;

BaseChannel led;
BaseConfig config;
ButtonInterrupt button;
SerialCommander cmd;

void setup() {
  Serial.begin(115200);
  
  config.setDynamicConfig(12, 2);
  led.attachConfig(config.getConfigData());
  led.initialize();
  
  cmd.init(&led, &config, &button);
  cmd.initWiFi();  // Initialize WiFi AP
  
  Serial.println("Type 'help' for commands");
}

void loop() {
  led.runAutoLight();
  cmd.process();  // Process serial commands
}

Constructor

SerialCommander
constructor
Create SerialCommander instance

Initialization

init
void
Initialize commander with AutoLight components
initWiFi
void
Initialize WiFi access point from preferences
process
void
Process incoming serial commands (call in loop)

Access Control

SerialCommander uses 4-level permission system:
typedef enum {
    SERIAL_DISABLED = 0,      // No access
    SERIAL_READ_ONLY = 1,     // View status only
    SERIAL_SAFE_CONTROL = 2,  // LED and sequence control
    SERIAL_FULL_ACCESS = 3    // All commands including WiFi
} SerialMode;
setMode
void
Set access mode
getMode
SerialMode
Get current access mode
activate
void
Activate elevated permissions (5-minute timeout)
deactivate
void
Deactivate elevated permissions

Command Categories

WiFi Commands

wifi
void
WiFi management commands
Available Commands:
wifi ap <ssid> <password>     # Start access point
wifi sta <ssid> <password>    # Connect to WiFi network
wifi scan                     # Scan available networks
wifi status                   # Show connection status
wifi restart                  # Restart WiFi AP
wifi reset                    # Reset to default credentials
wifi clients                  # Show connected clients

LED Commands

led_control
void
LED control commands
Available Commands:
led on                        # Turn all LEDs on
led off                       # Turn all LEDs off
led test <channel>            # Test specific channel
led status                    # Show all channel states
led next                      # Next sequence mode
led prev                      # Previous sequence mode

Sequence Commands

sequence
void
Sequence management commands
Available Commands:
sequence set <mode>           # Set sequence (0-15)
sequence map enable           # Enable sequence filtering
sequence map set 2,5,7,10     # Set active sequences
sequence map show             # Display current mapping
sequence delay <ms>           # Set timing delay (30-300ms)

PCF8574 Commands

pcf_manage
void
PCF8574 debugging and management
Available Commands:
pcf scan                      # Scan I2C bus for devices
pcf test <address>            # Test PCF at hex address (e.g., 0x27)
pcf status                    # Show all PCF states
pcf reset <address>           # Reset specific PCF
pcf write <address> <data>    # Write byte to PCF
pcf read <address>            # Read byte from PCF

Button Commands

button
void
Button configuration commands
Available Commands:
button mode <0-3>             # Set button mode
button test <index>           # Test button action
button config                 # Show current config

Serial Access Commands

serial_manage
void
Serial access management
Available Commands:
serial activate <level>       # Activate permission level (0-3)
serial deactivate             # Deactivate elevated permissions
serial mode                   # Show current access level

Help Command

help
void
Display help information

Internal Methods

loadWiFiPreferences
void
Load WiFi credentials from NVS
startAccessPoint
void
Start WiFi access point
startStationMode
void
Start WiFi station mode
showWiFiInfo
void
Display WiFi connection information
showConnectedClients
void
Show connected WiFi clients
scanI2CBus
void
Scan and display I2C devices
testSinglePCF
void
Test individual PCF8574
showAllPCFStatus
void
Display status of all PCF8574s

WiFiAPConfig Structure

struct WiFiAPConfig {
    char ssid[32];                      // AP SSID
    char password[64];                  // AP password
    bool is_loaded_from_preferences;    // Loaded from NVS
};

Usage Examples

Basic Setup

SerialCommander cmd;

void setup() {
  Serial.begin(115200);
  
  cmd.init(&led, &config);
  cmd.initWiFi();
}

void loop() {
  cmd.process();
}

Access Control Example

> serial activate 3
Activated FULL_ACCESS mode (timeout: 5 minutes)

> wifi ap MyAutoLight MySecurePassword
Access point started
SSID: MyAutoLight
IP: 192.168.4.1

> serial deactivate
Access level deactivated

PCF Debugging

> pcf scan
Scanning I2C bus...
Found device at 0x27
Found device at 0x38
Total devices: 2

> pcf test 0x27
Testing PCF8574 at 0x27
Writing 0xFF... OK
Reading back... 0xFF
Writing 0x00... OK
Test complete

> pcf status
PCF 0x27: Active, 8 channels
PCF 0x38: Active, 8 channels

LED Testing

> led status
Channel 0: OFF
Channel 1: OFF
Channel 2: OFF
...
Total: 12 channels

> led test 5
Testing channel 5...
ON... OFF... ON... OFF
Test complete

> sequence set 7
Sequence changed to mode 7

> sequence delay 100
Delay set to 100ms

Sequence Mapping

> sequence map enable
Sequence mapping enabled

> sequence map set 2,5,7,10
Active sequences: 2, 5, 7, 10

> sequence map show
Sequence Mapping:
  API Index 0 -> Sequence 2
  API Index 1 -> Sequence 5
  API Index 2 -> Sequence 7
  API Index 3 -> Sequence 10

Access Level Requirements

Command CategoryRequired Level
helpREAD_ONLY (1)
led statusREAD_ONLY (1)
led on/off/next/prevSAFE_CONTROL (2)
sequence setSAFE_CONTROL (2)
pcf scan/statusSAFE_CONTROL (2)
wifi commandsFULL_ACCESS (3)
pcf write/resetFULL_ACCESS (3)

Timeout Behavior

Elevated permissions automatically expire after 5 minutes (300,000 ms) of inactivity. The timeout is checked on each command execution.
static const uint32_t TIMEOUT_MS = 300000;  // 5 minutes

Best Practices

Security

Use access control for production systems

Debugging

PCF scan before configuration to verify hardware

Testing

Use ‘led test’ to verify individual channels

Monitoring

Use ‘led status’ to monitor real-time LED states

Platform Support

SerialCommander requires ESP32 for WiFi features and Preferences library support.

ESP32

Full support with all features

Build docs developers (and LLMs) love