Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/laniot/core

LAN-first WSS bridge for serial devices using a ESP32 (TLS, RS-232, WebSocket)
https://github.com/laniot/core

certificate-mager esp32 esp32-s3 esp32s3 freertos industrial-iot iot lan rs232 tls uart websocket wss

Last synced: about 1 month ago
JSON representation

LAN-first WSS bridge for serial devices using a ESP32 (TLS, RS-232, WebSocket)

Awesome Lists containing this project

README 

          
# LAN-IOT Multi-tasking System for ESP32-S3



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.



## Why LAN-First Security?



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



### The Problem We Solve

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.



## Features



- **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



## System Components



### 1. WiFi Manager (`wifi_manager.c/h`)

- Manages WiFi connections and credentials

- Automatic AP mode when no credentials are stored

- NVS-based credential storage

- Event-driven WiFi state management



### 2. Certificate Manager (`cert_manager.c/h`)

- Requests SSL certificates from remote signer

- Stores and manages certificates in NVS

- Handles certificate validation and renewal



### 3. Web Server (`web_server.c/h`)

- HTTP server for captive portal (AP mode)

- HTTPS server for secure operations (STA mode)

- RESTful API endpoints for configuration

- Modern web interface with JavaScript



### 4. Main Application (`main.c`)

- FreeRTOS task management

- System initialization

- Inter-task communication



### 5. UART Broadcast Service (`uart_broadcast.c/h`)

- 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



### 6. WebSocket Secure Service (`wss_service.c/h`)

- 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



### 7. TCP Server Service (`tcp_server_service.c/h`)

- 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



### 8. Button Service (`button_service.c`)

- 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)



## Configuration



### Remote Signer

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](#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 Configuration

- **Device ID**: `LAN-IOT-TEST-001`

- **AP SSID**: `LAN-IOT-Setup`

- **AP Password**: `iot123456`



## API Endpoints



### HTTP (Captive Portal)

- `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



### HTTPS (Secure Mode)

- `GET /` - Secure landing page

- `GET /api/status` - System status



## Build and Flash



### Initial Configuration



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



1. **Copy the template configuration**:

   ```bash

   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.



### Build Steps



1. **Setup ESP-IDF Environment**:

   ```bash

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

   ```



2. **Configure Project** (optional):

   ```bash

   idf.py menuconfig

   ```



3. **Build Project**:

   ```bash

   idf.py build

   ```



4. **Flash to ESP32-S3**:

   ```bash

   idf.py -p /dev/ttyUSB0 flash monitor

   ```



## Usage



### Initial Setup

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



### Web Interface

- **Captive Portal**: Modern, responsive interface for WiFi configuration

- **Secure Portal**: Status dashboard showing device information and security status



## System Flow



### Operational Sequence

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



### Automatic Reconnection

- WiFi automatically reconnects on connection loss

- Certificates persist across reboots (valid for 365 days)

- No internet required after initial certificate acquisition



## Task Architecture



### FreeRTOS Tasks

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



## Memory Management

- Uses SPIRAM for large buffers

- NVS for persistent storage

- Dynamic memory allocation for JSON parsing

- Proper cleanup of allocated resources



## Security Features

- SSL/TLS encryption for secure communication

- Certificate-based authentication

- Secure credential storage in NVS

- Input validation and sanitization



## Troubleshooting



### Common Issues

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



### Debugging

- Enable verbose logging in `sdkconfig`

- Use `idf.py monitor` for real-time logs

- Check NVS storage using `nvs_partition_gen.py`



## Hardware Requirements



### ESP32-S3 Configuration

- **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



### Partition Configuration

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



| Partition | Type | Subtype | Offset | Size | Description |

|-----------|------|---------|--------|------|-------------|

| nvs | data | nvs | 0x9000 | 20KB | Non-volatile storage for WiFi credentials, certificates, and settings |

| otadata | data | ota | 0xE000 | 8KB | OTA data partition |

| phy_init | data | phy | 0xF000 | 4KB | PHY initialization data |

| factory | app | factory | 0x10000 | 1.5MB | Main application firmware |

| storage | data | spiffs | 0x190000 | 448KB | File storage (future use) |



**Total Flash Usage**: ~2MB



## Dependencies



### ESP-IDF Version

- **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.



### Other Dependencies

- FreeRTOS (included with ESP-IDF)

- mbedTLS for SSL/TLS

- ESP32-S3 with SPIRAM (recommended)

- WiFi connectivity (2.4 GHz)

- Internet access for certificate requests



## Contributors



This project was created and is maintained by Carlos Huggins ([@carloshuggins](https://github.com/carloshuggins)) and the LAN-IOT community.



See [CONTRIBUTORS.md](CONTRIBUTORS.md) for a complete list of contributors.



## Contributing



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



## License



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



Copyright 2025 Carlos Huggins & LAN-IOT Project Contributors



### Third-Party Components



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](NOTICE) file for complete attribution information.