7. ACRouter Command Reference
Version: 1.0.0
Date: 2025-01-15
Complete guide for ACRouter serial terminal and REST API commands.
Table of Contents
- General Commands
- Router Control
- Configuration Management
- WiFi Network
- Web Server
- Time Synchronization
- OTA Firmware Updates
- Hardware Configuration
- Current Sensors
- REST API Reference
- Quick Start Examples
- Notes
General Commands
help
Display complete command reference.
help
status
Show current router status including mode, state, dimmer level, and power consumption.
status
Example output:
=== Router Status ===
Mode: AUTO
State: INCREASING
Dimmer: 45%
Power: 1250.3 W
Gain: 150.0
Thresh: 50.0 W
=====================
Router Control
router-mode
Set the router operating mode.
Modes:
- off or 0 - Router disabled
- auto or 1 - Solar Router mode (minimize grid import/export)
- eco or 2 - Economic mode (avoid grid import, allow export)
- offgrid or 3 - Offgrid mode (solar/battery autonomous)
- manual or 4 - Manual dimmer control
- boost or 5 - Maximum power routing
Usage:
router-mode auto # Set auto mode
router-mode manual # Set manual mode
router-mode # Show current mode
⚠️ Note: Changes are saved to NVS immediately.
router-dimmer
Control specific dimmer output level.
Parameters:
- ID - Dimmer identifier: 1, 2, or all
- value - Power level (0-100%)
Usage:
router-dimmer 1 75 # Set dimmer 1 to 75%
router-dimmer all 50 # Set all dimmers to 50%
router-dimmer # Show current level
⚠️ Note: Setting dimmer automatically switches to MANUAL mode.
router-status
Show detailed router status (same as status command).
router-status
router-calibrate
Run power meter calibration routine.
router-calibrate
🚧 Status: Feature under development.
debug-adc
Enable/disable debug logging output from the power meter (PowerMeterADC).
Usage:
debug-adc # Set debug output period
debug-adc # Show current settings
Parameters:
- Debug output period in seconds:0- Disable debug output>0- Enable with specified period (e.g.,5= every 5 seconds)
Examples:
# Enable debug output every 5 seconds
debug-adc 5
# Output: debug-adc = 5 seconds (enabled)
# Disable debug output
debug-adc 0
# Output: debug-adc = DISABLED
# Show current settings
debug-adc
# Output: debug-adc = 5 seconds (or DISABLED)
Debug Information:
When debug output is enabled, detailed ADC operation information will be logged:
For voltage sensor:
VOLTAGE CH0: rms=230.5V, phase=POSITIVE (pos=12345, neg=-11234)
For current sensors:
DEBUG CH1 [GPIO39] CURRENT_GRID: dc_avg=2048.3, rms_adc=145.23, vdc=0.512V, amps=25.60
Phase: current=POSITIVE (pos=13456, neg=-12345), correlation: same=3850, diff=150 -> CONSUMING
Fields:
rms- RMS voltage in voltsphase- Signal phase (POSITIVE/NEGATIVE/BALANCED)pos/neg- Sum of positive/negative half-periods (for asymmetry diagnostics)dc_avg- Average DC value (should be around 2048 for 12-bit ADC)rms_adc- RMS value in ADC unitsvdc- Sensor output voltage (V)amps- Measured current (A)same/diff- Voltage-current phase correlation:same > diff→ CONSUMING (importing from grid)diff > same→ SUPPLYING (exporting to grid)
Applications:
- Sensor troubleshooting
- Verify correct current direction detection
- Analyze signal asymmetry (pos/neg sums)
- Debug sensor calibration
- Monitor measurement quality
⚠️ Important: Debug output creates significant load on the Serial port. Use only for diagnostics, disable after troubleshooting.
📝 Note: This setting is NOT saved to NVS. Debug output will be disabled after reboot.
Configuration Management
All configuration commands save values to NVS (Non-Volatile Storage) immediately.
config-show
Display all configuration parameters.
config-show
config-reset
Reset all configuration to factory defaults.
config-reset
⚠️ Warning: This will erase all custom settings.
config-gain [value]
Set control loop gain parameter (affects response speed).
Range: 1-1000 | Default: 150
config-gain 200 # Set gain
config-gain # Show current gain
Effect: Higher values = faster response, lower values = more stable.
config-threshold [value]
Set balance threshold for auto mode.
Range: 0-100 W | Default: 50 W
config-threshold 30 # Set threshold
config-threshold # Show current threshold
Effect: Router tries to keep grid power within ±threshold of zero.
config-manual [value]
Set default manual mode dimmer level.
Range: 0-100% | Default: 0%
config-manual 50 # Set manual level
config-manual # Show current level
config-vcoef [value]
Set voltage calibration coefficient.
Range: 0.1-10.0 | Default: 1.0
config-vcoef 1.05 # Set coefficient
config-vcoef # Show current value
Effect: Multiplier for voltage measurements (sensor calibration).
config-icoef [value]
Set current measurement coefficient.
Range: 0.1-100.0 A/V | Default: 30.0 A/V
config-icoef 33.0 # Set coefficient
config-icoef # Show current value
Effect: Converts sensor voltage to current measurement.
config-ithresh [value]
Set current detection threshold.
Range: 0.01-10.0 A | Default: 0.1 A
config-ithresh 0.15 # Set threshold
config-ithresh # Show current value
Effect: Minimum current to detect active power flow.
config-pthresh [value]
Set power detection threshold.
Range: 1-1000 W | Default: 10 W
config-pthresh 15 # Set threshold
config-pthresh # Show current value
Effect: Minimum power to detect active consumption/generation.
WiFi Network
wifi-status
Display WiFi connection status, IP addresses, and saved credentials.
wifi-status
Status Fields:
- IDLE - Not initialized
- AP_ONLY - Access Point only
- STA_CONNECTING - Connecting to network
- STA_CONNECTED - Connected as client
- AP+STA - Both AP and STA active
- STA_FAILED - Connection failed
Signal Strength Guide:
- -30 to -50 dBm - Excellent
- -51 to -70 dBm - Good
- -71 to -85 dBm - Fair
- -86 to -100 dBm - Poor
wifi-scan
Scan for available WiFi networks.
wifi-scan
wifi-connect [password]
Connect to WiFi network and save credentials to NVS.
Parameters:
- ssid - Network name (required)
- For SSID with spaces, use double quotes: "My Network"
- password - Network password (optional for open networks)
- For passwords with spaces, use double quotes: "My Pass 123"
Usage:
# Simple connection (no spaces)
wifi-connect MyHomeNetwork MyPassword123
wifi-connect GuestNetwork # For open networks
# SSID with spaces (quoted)
wifi-connect "My Home Network" MyPassword123
# Both SSID and password with spaces (both quoted)
wifi-connect "Coffee Shop WiFi" "welcome guest 2024"
Examples:
# Connect to secured network
wifi-connect MyNetwork SecurePass2024
# Output: Connecting to: MyNetwork
# Password: ***
# Connect to network with spaces in name
wifi-connect "TP-LINK Home" MyPassword
# Output: Connecting to: TP-LINK Home
# Password: ***
# Connect to open network
wifi-connect PublicWiFi
# Output: Connecting to: PublicWiFi
# No password (open network)
Behavior:
1. Connects to specified network
2. On success, credentials are automatically saved to NVS
3. On next boot, router will auto-connect
4. AP mode remains active (AP+STA mode)
⚠️ Security Note: Password is transmitted in plaintext over serial.
wifi-disconnect
Disconnect from current STA network (AP remains active).
wifi-disconnect
Effect: Router returns to AP-only mode. Saved credentials remain in NVS.
wifi-forget
Clear saved WiFi credentials from NVS.
wifi-forget
Effect: Router will not auto-connect on next boot. Current connection remains active.
Web Server
web-status
Display web server status, access URLs, and API endpoints.
web-status
web-start
Start the web server.
web-start
Default Ports:
- HTTP: 80
- WebSocket: 81
web-stop
Stop the web server.
web-stop
web-urls
Display all web interface access URLs.
web-urls
Web Pages:
- / - Main control interface (future)
- /wifi - WiFi configuration page
- /ota - Firmware update page
Time Synchronization
time-status
Display NTP time synchronization status.
time-status
Default NTP Servers:
- pool.ntp.org
- time.google.com
time-sync
Force immediate NTP synchronization.
time-sync
OTA Firmware Updates
ota-status
Display OTA update status and access URLs.
ota-status
Update Process:
1. Open OTA URL in web browser
2. Select firmware binary file (.bin)
3. Upload and wait for completion
4. Device will automatically reboot
⚠️ Important: Do not power off or disconnect during update!
Safety Features:
- Critical tasks suspended during update
- Watchdog protection
- Rollback on failure
Hardware Configuration
Commands for voltage and current sensor configuration, NVS version management, and system operations.
Hardware Reset - hardware-reset
Reset hardware configuration to factory defaults (keeps NVS structure).
hardware-reset
Process:
- Stops PowerMeterADC to prevent DMA conflicts
- Resets all hardware settings to factory defaults
- Saves to NVS
Example output:
Resetting hardware configuration to factory defaults...
Stopping PowerMeterADC...
Hardware configuration reset successful
IMPORTANT: Reboot required for changes to take effect!
Use 'reboot' command to restart
⚠️ Important: Reboot required after this command (reboot).
Voltage Sensor - hardware-voltage-show
Display current voltage sensor configuration.
hardware-voltage-show
Example output:
========== Voltage Sensor ==========
Channel: 0
GPIO: 35
Type: VOLTAGE_AC
Driver: ZMPT107
Nominal VDC: 0.700 V
Multiplier: 321.43
Offset: 0.00
Status: ENABLED
====================================
Voltage Sensor - hardware-voltage-config-type
Set voltage sensor driver type.
hardware-voltage-config-type
Parameters:
- - Sensor type:
- ZMPT107 - ZMPT107 sensor (0.70V RMS nominal)
- ZMPT101B - ZMPT101B sensor (1.0V RMS nominal)
- CUSTOM - Custom sensor
Example:
hardware-voltage-config-type ZMPT107
Voltage Sensor - hardware-voltage-config-port
Set GPIO pin for voltage sensor.
hardware-voltage-config-port GPIO
Parameters:
- - GPIO number (32-39 for ESP32 ADC1)
Example:
hardware-voltage-config-port GPIO35
⚠️ Important: Reboot required after GPIO changes (reboot).
Voltage Sensor - hardware-voltage-calibrate ⭐
Automatic voltage sensor calibration with VDC measurement.
hardware-voltage-calibrate
Parameters:
- - Grid voltage measured with multimeter (VAC RMS)
- Range: 50-300V
Calibration Process:
- Measure grid voltage with multimeter (AC RMS mode)
- Enter command with measured value
- System automatically:
- Measures current sensor VDC output (RMS)
- Calculates multiplier:
multiplier = V_measured / V_sensor - Saves calibrated nominal_vdc and multiplier to NVS
- Reboot device (
reboot)
Example:
# Multimeter shows 230.5V
hardware-voltage-calibrate 230.5
Output:
========== Voltage Calibration ==========
Measuring sensor VDC output...
Measured grid voltage: 230.50 V AC (from multimeter)
Measured sensor VDC: 0.814 V (auto-measured)
Calculated multiplier: 283.17
=========================================
Calibration saved successfully!
Updated:
- Nominal VDC: 0.814 V
- Multiplier: 283.17
IMPORTANT: Reboot required for changes to take effect!
Use 'reboot' command to restart
Benefits of Automatic Calibration:
✅ No need to manually adjust sensor potentiometer
✅ Works with any sensor output voltage
✅ Automatically updates nominal_vdc
✅ More accurate and faster
📝 Note: Old method (manually adjusting potentiometer to 0.7V) is no longer required!
Voltage Sensor - hardware-voltage-config-multiplier
Directly set multiplier (for advanced users).
hardware-voltage-config-multiplier
Parameters:
- - Multiplier (0.1-1000)
⚠️ Recommendation: Use hardware-voltage-calibrate instead of manual multiplier setting.
Current Sensors
hardware-current-list
Display all configured current sensors with their bindings.
hardware-current-list
Example output:
========== Configured Current Sensors ==========
[CH1] GRID GPIO39 SCT013-50A 50.00 A/V Offset: 0.00V
[CH2] SOLAR GPIO36 SCT013-30A 30.00 A/V Offset: 0.00V
[CH3] LOAD_1 GPIO34 ACS712-20A 15.15 A/V Offset: 1.65V
================================================
Fields:
CH- ADC channel number (0-3)- Binding - Functional role (GRID, SOLAR, LOAD_1..LOAD_8)
GPIO- GPIO pin (32-39)- Sensor type - Current sensor model
A/V- Calibration multiplierOffset- DC offset (for ACS712 sensors)
hardware-current-config GPIO
Configure current sensor: set type, GPIO pin and functional binding.
Parameters:
- Functional binding:GRID- Grid connection (import/export)SOLAR- Solar panelLOAD_1,LOAD_2, ...LOAD_8- Loads 1-8- Sensor type:- SCT-013 series (AC current transformers, 0-1V output):
SCT013-5A- 0-5A, 1V @ 5ASCT013-10A- 0-10A, 1V @ 10ASCT013-20A- 0-20A, 1V @ 20ASCT013-30A- 0-30A, 1V @ 30ASCT013-50A- 0-50A, 1V @ 50ASCT013-60A- 0-60A, 1V @ 60ASCT013-80A- 0-80A, 1V @ 80ASCT013-100A- 0-100A, 1V @ 100A
- ACS712 series (Hall effect sensors, 2.5V center @ 5V):
ACS712-5A- ±5AACS712-20A- ±20AACS712-30A- ±30A
CUSTOM- Custom sensor- GPIO number (32-39, ADC1 only)
Usage:
# Configure grid sensor: SCT-013-50A on GPIO39
hardware-current-config GRID SCT013-50A GPIO39
# Configure solar panel: SCT-013-100A on GPIO36
hardware-current-config SOLAR SCT013-100A GPIO36
# Configure load 1: ACS712-20A on GPIO34
hardware-current-config LOAD_1 ACS712-20A GPIO34
Example output:
========== Current Sensor Configured ==========
Binding: GRID
Channel: 1
GPIO: 39
Driver: SCT013-50A
Nominal: 50.0 A
Multiplier: 50.00
DC Offset: 0.00 V
===============================================
IMPORTANT: Reboot required for changes to take effect!
Use 'reboot' command to restart
NOTE: ACS712 sensors have DC bias (1.65V after divider)
Use 'hardware-current-calibrate-zero GRID' to calibrate zero point
Channel selection algorithm:
The system automatically selects ADC channel by priority:
- Priority 1: Channel with matching GPIO (reconfigure existing sensor)
- Priority 2: Channel with same binding type (update sensor type)
- Priority 3: First free channel (type = NONE)
- Priority 4: Any channel with current sensor (migration from old types)
⚠️ Important: Reboot required (reboot) for changes to take effect.
hardware-current-show
Display detailed information about specific current sensor.
Parameters:
- Sensor binding (GRID,SOLAR,LOAD_1..LOAD_8)
Usage:
hardware-current-show GRID
Example output:
========== Current Sensor Configuration ==========
Binding: GRID
Channel: 1
GPIO: 39
Driver: SCT013-50A
Multiplier: 50.00
DC Offset: 0.00 V
Status: ENABLED
===================================================
hardware-current-delete
Delete current sensor configuration and free ADC channel.
Parameters:
- Sensor binding (GRID,SOLAR,LOAD_1..LOAD_8)
Usage:
hardware-current-delete GRID
Example output:
Successfully deleted sensor: GRID
Channel: 1
GPIO: 39
Driver: SCT013-50A
Channel is now free and can be reassigned.
IMPORTANT: Reboot required for changes to take effect!
Error (sensor not found):
ERROR: No sensor configured for binding: GRID
Use 'hardware-current-list' to see configured sensors
hardware-current-calibrate-zero
Calibrate zero point of current sensor (DC offset compensation).
Parameters:
- Sensor binding to calibrate
When to use:
- After installing a new sensor
- When readings drift (sensor shows current with no load)
- After adjusting potentiometer on ACS712 sensor
Calibration process:
- IMPORTANT: Disconnect load from sensor (current = 0A)
- Enter command
- System measures current DC offset
- Calculates and saves correcting offset to NVS
- Reboot device
Usage:
# Disconnect load from GRID sensor
# Ensure current through sensor = 0A
hardware-current-calibrate-zero GRID
Example output:
========== Zero-Point Calibration ==========
Ensure NO current is flowing through sensor!
Measuring DC offset...
NOTICE: Auto-calibration not yet implemented
PowerMeterADC automatically compensates DC offset
Manual adjustment not required in most cases
===========================================
📝 Note:
- SCT-013: Calibration usually not required (pure AC output)
- ACS712: Recommended for compensating center point drift (2.5V)
- PowerMeterADC automatically subtracts DC offset, this command compensates remaining drift
NVS Version - hw-version-show
Display NVS data format version and safe mode status.
hw-version-show
Example output (normal mode):
========== NVS Version Info ==========
Firmware version: 2
NVS version: 2
Status: OK
======================================
Example output (safe mode):
========== NVS Version Info ==========
Firmware version: 2
NVS version: 1
Status: SAFE MODE
Reason: NVS version mismatch (NVS: 1, Firmware: 2).
Use 'hw-erase-nvs' command to reset.
======================================
WARNING: PowerMeterADC is NOT initialized in safe mode!
System will continue with limited functionality:
- WiFi and WebServer: WORKING
- Manual dimmer control: WORKING
- Power measurements: DISABLED
Version History:
v1- Initial version (hardcoded ZMPT107 multiplier)v2- Added voltage_driver and nominal_vdc fields
📝 Safe mode is automatically activated on version mismatch to prevent system crashes.
NVS Reset - hw-erase-nvs
Completely erase all NVS data and reset to factory defaults.
hw-erase-nvs
Process:
- Command will ask for confirmation
- Enter
YES(in capital letters) - System erases all data from
hw_confignamespace - Loads factory defaults
- Saves settings with current version
Example:
hw-erase-nvs
Output:
WARNING: This will erase ALL hardware configuration!
Type 'YES' to confirm (timeout: 10s):
YES
Erasing NVS namespace 'hw_config'...
NVS namespace erased successfully
Factory defaults saved (version 2)
Hardware configuration reset complete!
IMPORTANT: Reboot required!
Use 'reboot' command to restart
⚠️ WARNING: This operation is irreversible! All custom sensor settings and GPIO configurations will be lost.
When to use:
- Upgrading to new firmware with incompatible NVS format
- Returning to factory hardware settings
- Troubleshooting configuration issues
System Reboot - reboot
Restart ESP32.
reboot
Output:
Rebooting in 1 second...
📝 Note: Required after:
- Changing GPIO pins
- Sensor calibration
- NVS reset
- Hardware configuration updates
REST API Reference
⚠️ Note: This section provides a quick reference for REST API endpoints. For integration with web applications, use these endpoints along with the serial commands described above.
Access URLs
Access Point Mode:
http://192.168.4.1/api/
Station Mode:
http:///api/
Use wifi-status command to find current IP address.
Status & Monitoring
GET /api/status - Complete router status
curl http://192.168.4.1/api/status
GET /api/metrics - Power metrics (lightweight, for polling)
curl http://192.168.4.1/api/metrics
GET /api/config - All configuration parameters
curl http://192.168.4.1/api/config
GET /api/info - System information
curl http://192.168.4.1/api/info
Configuration
POST /api/config - Update configuration
curl -X POST http://192.168.4.1/api/config \
-H "Content-Type: application/json" \
-d '{"control_gain": 200, "balance_threshold": 30}'
POST /api/config/reset - Reset to factory defaults
curl -X POST http://192.168.4.1/api/config/reset
Router Control
POST /api/mode - Set operating mode
Valid modes: off, auto, eco, offgrid, manual, boost
# Set AUTO mode (Solar Router)
curl -X POST http://192.168.4.1/api/mode \
-H "Content-Type: application/json" \
-d '{"mode": "auto"}'
# Set ECO mode (Economic, avoid import)
curl -X POST http://192.168.4.1/api/mode \
-H "Content-Type: application/json" \
-d '{"mode": "eco"}'
# Set OFFGRID mode (Autonomous solar/battery)
curl -X POST http://192.168.4.1/api/mode \
-H "Content-Type: application/json" \
-d '{"mode": "offgrid"}'
POST /api/dimmer - Set dimmer level (switches to MANUAL mode)
curl -X POST http://192.168.4.1/api/dimmer \
-H "Content-Type: application/json" \
-d '{"value": 75}'
POST /api/manual - Set manual level (alternative endpoint)
curl -X POST http://192.168.4.1/api/manual \
-H "Content-Type: application/json" \
-d '{"value": 50}'
WiFi Management
GET /api/wifi/status - WiFi status and IP addresses
curl http://192.168.4.1/api/wifi/status
GET /api/wifi/scan - Scan for networks
curl http://192.168.4.1/api/wifi/scan
POST /api/wifi/connect - Connect to network (saves to NVS)
curl -X POST http://192.168.4.1/api/wifi/connect \
-H "Content-Type: application/json" \
-d '{"ssid": "MyNetwork", "password": "MyPassword"}'
POST /api/wifi/disconnect - Disconnect from STA network
curl -X POST http://192.168.4.1/api/wifi/disconnect
POST /api/wifi/forget - Clear saved credentials from NVS
curl -X POST http://192.168.4.1/api/wifi/forget
Web API Usage Examples
Python (requests):
import requests
base = "http://192.168.4.1/api"
# Get status
status = requests.get(f"{base}/status").json()
print(f"Mode: {status['mode']}, Dimmer: {status['dimmer']}%")
# Set ECO mode
requests.post(f"{base}/mode", json={"mode": "eco"})
# Update gain
requests.post(f"{base}/config", json={"control_gain": 250})
# Monitor metrics (polling)
import time
while True:
metrics = requests.get(f"{base}/metrics").json()
print(f"Grid: {metrics['metrics']['power_grid']}W")
time.sleep(2)
JavaScript (Fetch):
const base = "http://192.168.4.1/api";
// Get status
fetch(`${base}/status`)
.then(r => r.json())
.then(d => console.log(`Mode: ${d.mode}, Dimmer: ${d.dimmer}%`));
// Set OFFGRID mode
fetch(`${base}/mode`, {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({mode: 'offgrid'})
});
// Polling metrics every 2 seconds
setInterval(() => {
fetch(`${base}/metrics`)
.then(r => r.json())
.then(d => console.log(`Grid: ${d.metrics.power_grid}W`));
}, 2000);
Bash (curl + jq):
BASE="http://192.168.4.1/api"
# Get status (formatted with jq)
curl -s "$BASE/status" | jq .
# Set AUTO mode
curl -X POST "$BASE/mode" \
-H "Content-Type: application/json" \
-d '{"mode": "auto"}'
# Monitor loop
while true; do
curl -s "$BASE/metrics" | jq '.metrics'
sleep 5
done
Quick Start Examples
Initial Setup
# Check status
status
# Scan for WiFi networks
wifi-scan
# Connect to WiFi (credentials saved to NVS)
wifi-connect MyNetwork MyPassword
# Check WiFi status
wifi-status
# Set router to auto mode
router-mode auto
# Adjust gain for faster response
config-gain 200
Manual Control
# Switch to manual mode
router-mode manual
# Set dimmer to 50%
router-dimmer 1 50
# Set all dimmers to 100%
router-dimmer all 100
# Return to auto mode
router-mode auto
Troubleshooting
# Check all systems
status
wifi-status
web-status
time-status
# Reset configuration if needed
config-reset
# Reconnect WiFi
wifi-connect MyNetwork MyPassword
# Force time sync
time-sync
# Restart web server
web-stop
web-start
Notes
Command Format
- Commands are case-insensitive
- Parameters are space-separated
Data Persistence
- All
config-*commands save to NVS immediately - WiFi credentials saved automatically on successful connection
- Settings persist across reboots
Safety Features
- Dimmer limits: 0-100%
- Parameter range validation
- Watchdog protection during OTA
- Critical task suspension during updates
Web Interface
- Access via any browser
- Responsive design for mobile
- Real-time status updates
- No authentication (use firewall rules)
Related Documentation
- 01_OVERVIEW.md - Project overview and features
- 02_COMPILATION.md - Build instructions
- 03_STRUCTURE.md - Application architecture
- 04_ROUTER_MODES.md - Router operating modes explained
- 05_API_REFERENCE_EN.md - Component API reference
- 06_MAIN_APPLICATION.md - Main application entry point
- 07_COMMANDS.md - Russian version (Команды и REST API)
Firmware Version: 1.0.0
Last Updated: 2025-01-15