A comprehensive multi-tasking system built with FreeRTOS for ESP32-S3 that provides secure local-area network (LAN) communication for IoT devices in remote locations with intermittent internet connectivity.

This project addresses a critical challenge in IoT deployments: secure data access in remote locations with unreliable internet. Unlike traditional cloud-centric IoT solutions that require constant internet connectivity, LAN-IOT focuses on secure local communication:

• Local HTTPS Server: Serves web interfaces directly from the device over HTTPS
• Secure WebSocket (WSS): Enables real-time data streaming from RS232/UART to browsers and clients
• Browser Security Compliance: Modern browsers require HTTPS pages to connect to secure WebSocket (WSS) endpoints - this system provides both
• Remote Certificate Signing: Devices request certificates once when internet is available, then operate independently on the LAN
• No Cloud Dependency: After initial setup, all data flows locally - critical for remote locations with intermittent connectivity
• TCP Server Support: Provides both WSS (for browsers) and raw TCP (for legacy devices) simultaneously

In many remote industrial locations (farms, mines, oil fields), internet connectivity is:

• Intermittent or unreliable
• Expensive or bandwidth-limited
• Subject to outages

Traditional cloud-based IoT solutions fail in these scenarios. LAN-IOT enables:

1. Secure local data access via HTTPS/WSS
2. Browser-based monitoring without cloud dependency
3. Real-time RS232/UART data streaming to multiple clients
4. Certificate-based security without constant internet access

This is one of the few (if not the only) IoT projects specifically designed for secure LAN-first operation with proper SSL/TLS certificates, making it ideal for remote industrial deployments.

• Multi-tasking Architecture: Built with FreeRTOS for concurrent operations
• WiFi Management: Automatic WiFi credential management with NVS storage
• Captive Portal: Automatic AP mode with web-based WiFi configuration
• Secure Web Server: HTTPS server with SSL/TLS certificates from remote signer
• Certificate Management: Automatic certificate request and storage
• Web Interface: Modern, responsive web interface for configuration

• Manages WiFi connections and credentials
• Automatic AP mode when no credentials are stored
• NVS-based credential storage
• Event-driven WiFi state management

• Requests SSL certificates from remote signer
• Stores and manages certificates in NVS
• Handles certificate validation and renewal

• HTTP server for captive portal (AP mode)
• HTTPS server for secure operations (STA mode)
• RESTful API endpoints for configuration
• Modern web interface with JavaScript

• FreeRTOS task management
• System initialization
• Inter-task communication

• Centralized UART data distribution
• Reads from UART2 (RS232) and broadcasts to all subscribers
• Supports multiple simultaneous subscribers (WSS, TCP, etc.)
• Non-blocking architecture for real-time data flow

• Secure WebSocket server for real-time bidirectional communication
• Subscribes to UART broadcast for incoming serial data
• Broadcasts data to all connected WebSocket clients
• Configurable enable/disable via admin interface

• Raw TCP server for legacy device compatibility
• Subscribes to UART broadcast for incoming serial data
• Supports multiple simultaneous TCP clients (up to 8)
• Configurable port (default: 5000)
• TCP_NODELAY enabled for real-time data transmission

• GPIO0 button monitoring with debouncing
• Short press: Sends test message to UART
• Long press (3 seconds): Initiates wipe & reset
• Broadcasts button events to all services (WSS and TCP)

The system uses a remote certificate signing service to generate device-specific SSL/TLS certificates:

• Purpose: Each device gets unique certificates signed by a trusted Certificate Authority
• Configuration: Signer URL and authentication token must be configured in main/app_config.h (see Build and Flash section)
• Security: The authentication token ensures only authorized devices can request certificates
• Process: On first boot, the device contacts the signer with its unique ID and IP address
• Certificate Validity: 365 days (configurable)
• Storage: Certificates are securely stored in NVS for persistent use across reboots

Important: The app_config.h file contains sensitive credentials and is excluded from version control. Use app_config.h.bak as a template to create your local configuration.

• Device ID: LAN-IOT-TEST-001
• AP SSID: LAN-IOT-Setup
• AP Password: iot123456

• GET / - Captive portal interface
• GET /api/wifi/scan - Scan for available networks
• POST /api/wifi/connect - Connect to WiFi network
• GET /api/status - System status

• GET / - Secure landing page
• GET /api/status - System status

Important: Before building, you need to create your local configuration file:

1. Copy the template configuration:

   cp main/app_config.h.bak main/app_config.h

2. Edit main/app_config.h with your specific settings:

   • Signer URL: Update APP_CFG_SIGNER_URL with your certificate signing service URL
   • Authentication Token: Update APP_CFG_SIGNER_TOKEN with your authentication token
   • Device Settings: Customize device name prefix, AP SSID, passwords, etc.

   Note: app_config.h is in .gitignore to prevent accidentally committing sensitive credentials. The app_config.h.bak file serves as a template with placeholder values.

1. Setup ESP-IDF Environment:

   . $HOME/esp/esp-idf/export.sh

2. Configure Project (optional):

   idf.py menuconfig

3. Build Project:

   idf.py build

4. Flash to ESP32-S3:

   idf.py -p /dev/ttyUSB0 flash monitor

1. Power on the ESP32-S3
2. Device will start in AP mode (LAN-IOT-Setup)
3. Connect to the AP using password iot123456
4. Captive portal will open automatically
5. Select your WiFi network and enter password
6. Device will save credentials and restart
7. Device will connect to your WiFi and request SSL certificates
8. Secure HTTPS server will start on port 443

• Captive Portal: Modern, responsive interface for WiFi configuration
• Secure Portal: Status dashboard showing device information and security status

1. Initial Boot: Device starts in AP mode with captive portal
2. WiFi Configuration: User connects to AP and configures WiFi credentials
3. Credential Storage: WiFi credentials are saved to NVS for persistence
4. Network Connection: Device connects to the configured WiFi network
5. NTP Synchronization: System time is synchronized via NTP
6. Certificate Request: Device requests SSL certificates from remote signer
7. Certificate Storage: Certificates are saved to NVS
8. Secure Server Launch: HTTPS server starts with valid certificates
9. Operational Mode: Device runs secure web server with HTTPS/WSS/TCP services

• WiFi automatically reconnects on connection loss
• Certificates persist across reboots (valid for 365 days)
• No internet required after initial certificate acquisition

1. WiFi Management Task (Core 0, Priority 5)

   • Manages WiFi connections and AP/STA mode switching
   • Handles automatic reconnection on failure
   • Monitors connection status and signal strength

2. Web Server Task (Core 1, Priority 4)

   • Manages HTTP server (captive portal) and HTTPS server (secure mode)
   • Handles web requests and API endpoints
   • Serves configuration interfaces

3. Certificate Request Task (Core 1, Priority 3)

   • Requests certificates from remote signer (one-time on first boot)
   • Manages certificate storage in NVS
   • Handles certificate validation

4. UART Broadcast Task (Core 1, Priority configMAX_PRIORITIES - 3)

   • Reads data from UART2 (RS232)
   • Broadcasts to all subscribers (WSS, TCP)
   • Non-blocking architecture for real-time data flow

5. Button Service Task (Core 1, Priority configMAX_PRIORITIES - 4)

   • Monitors GPIO0 button with debouncing
   • Handles short press (test message) and long press (wipe & reset)
   • Broadcasts button events to all services

• Uses SPIRAM for large buffers
• NVS for persistent storage
• Dynamic memory allocation for JSON parsing
• Proper cleanup of allocated resources

• SSL/TLS encryption for secure communication
• Certificate-based authentication
• Secure credential storage in NVS
• Input validation and sanitization

1. WiFi Connection Failed: Check credentials and network availability
2. Certificate Request Failed: Verify internet connectivity and signer URL
3. Memory Issues: Check SPIRAM configuration and heap usage
4. Build Errors: Ensure all dependencies are properly configured

• Enable verbose logging in sdkconfig
• Use idf.py monitor for real-time logs
• Check NVS storage using nvs_partition_gen.py

• Module: ESP32-S3-WROOM-1 or compatible
• Flash: 2MB minimum (configured for 2MB)
• PSRAM: 2MB QSPI (optional but recommended)
• WiFi: 2.4 GHz 802.11 b/g/n
• UART: UART2 (GPIO19 TX, GPIO18 RX) for RS232 communication
• Button: GPIO0 for system control and wipe/reset functionality

The system uses a custom partition table optimized for 2MB flash:

Total Flash Usage: ~2MB

• Current Version: ESP-IDF v5.5.1
• Important Note: This project specifically uses ESP-IDF v5.5.1 due to certificate bundle compatibility issues
• Future Migration: Will upgrade to ESP-IDF v6.0+ once the embedded root certificate bundle is updated

Why v5.5.1? The ESP-IDF v6.0 certificate bundle removed or updated certain root certificates that are required to validate the remote certificate signing service domain. The v5.5.1 bundle includes the necessary GlobalSign and Google Trust Services root certificates that validate domains like *.replit.app. Once the v6.0 certificate bundle is updated to include these certificates, the project will be migrated.

• FreeRTOS (included with ESP-IDF)
• mbedTLS for SSL/TLS
• ESP32-S3 with SPIRAM (recommended)
• WiFi connectivity (2.4 GHz)
• Internet access for certificate requests

This project was created and is maintained by Carlos Huggins (@carloshuggins) and the LAN-IOT community.

See CONTRIBUTORS.md for a complete list of contributors.

We welcome contributions! Please see CONTRIBUTING.md for guidelines on how to contribute to this project.

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

Copyright 2025 Carlos Huggins & LAN-IOT Project Contributors

This project uses the following open-source components:

• ESP-IDF: Apache License 2.0
• FreeRTOS: MIT License
• mbedTLS: Apache License 2.0
• cJSON: MIT License

See NOTICE file for complete attribution information.