Skip to content

quick-start.md

Latest commit

 

History

History
261 lines (191 loc) · 7.69 KB

quick-start.md

File metadata and controls

261 lines (191 loc) · 7.69 KB

Quick Start Guide

Get your LAN IoT device up and running in 15 minutes.

Disclosure: As an Amazon Associate I earn from qualifying purchases made with links from the products on this document.

Prerequisites

Before you begin, ensure you have:

Step 1: Hardware Setup (5 minutes)

Assemble Your Device

  1. Assemble on Perfboard (recommended)

    • Mount ESP32S3 on perfboard
    • Connect RS232 module for serial communication
    • Add tactile button for reset/function
    • Use pin headers and jumper wires for connections
    • Connect GPIO43 (UART2 RX) to RS-232 TX
    • Connect GPIO44 (UART2 TX) to RS-232 RX
    • Connect GND to RS-232 GND
    • Connect 3V3 to RS-232 VCC
    • Connect GPIO3 to TAC BUTTON
    • Connect GND to TACT BUTTON

  2. Optional: Install in Enclosure

  3. Connect USB Cable

    • Plug USB-C cable into ESP32-S3
    • Connect to your computer

Step 2: Build Firmware (5 minutes)

Clone and Configure

# Clone the core firmware repository
git clone https://github.com/laniot/core.git
cd core

# Set up ESP-IDF environment
. $HOME/esp/esp-idf/export.sh

# Create configuration file from template
cp main/app_config.h.bak main/app_config.h

Edit Configuration

Open main/app_config.h and update:

// Certificate Signer Configuration
#define APP_CFG_SIGNER_URL "https://your-signer.example.com"
#define APP_CFG_SIGNER_TOKEN "your-auth-token-here"

// Device Configuration
#define APP_CFG_DEVICE_NAME_PREFIX "LAN-IOT"
#define APP_CFG_AP_SSID "LAN-IOT-Setup"
#define APP_CFG_AP_PASSWORD "iot123456"

Important: Keep your auth token secure! The app_config.h file is in .gitignore to prevent accidental commits.

Build and Flash

# Build the firmware
idf.py build

# Flash to ESP32-S3 (adjust port as needed)
idf.py -p /dev/ttyUSB0 flash

# Monitor serial output
idf.py -p /dev/ttyUSB0 monitor

Windows Users: Replace /dev/ttyUSB0 with COM3 (or appropriate COM port)
macOS Users: Use /dev/cu.usbserial-* or /dev/tty.usbserial-*

Step 3: Initial Configuration (3 minutes)

Connect to Captive Portal

  1. Watch for AP Mode

    • Device starts in Access Point mode
    • Look for WiFi network: LAN-IOT-Setup

  2. Connect to AP

    • SSID: LAN-IOT-Setup
    • Password: iot123456
    • Captive portal should open automatically

  3. Configure WiFi

    • Select your WiFi network from the scan results
    • Enter WiFi password
    • Click "Connect"
    • Device will save credentials and restart

Verify Connection

Watch the serial monitor for:

I (1234) wifi_manager: WiFi Connected
I (2345) wifi_manager: IP Address: 192.168.1.100
I (3456) cert_manager: Requesting certificates...
I (4567) cert_manager: Certificates received and stored
I (5678) web_server: HTTPS server started on port 443

Step 4: Access Secure Interface (2 minutes)

Find Your Device IP

Option 1: Serial Monitor (easiest)

  • Look for IP Address: 192.168.1.xxx in serial output

Option 2: Router Admin Page

  • Check DHCP client list
  • Look for device with hostname LAN-IOT-*

Option 3: Network Scanner

# Using nmap (if installed)
nmap -p 443 192.168.1.0/24

Access Web Interface

  1. Open your browser
  2. Navigate to: https://192.168.1.xxx (use your device's IP)
  3. Certificate Warning: You'll see a security warning
    • This is expected on first connection
    • Accept/proceed (certificate is valid, just not in browser's trust store)
  4. You should see the LAN IoT admin interface

Add Root CA to Browser (Optional)

To remove certificate warnings:

  1. Download root CA certificate from the IOT device
  2. Import into your Operating system trusted certificates
  3. See Certificate Management for details

Step 5: Test Communication

WebSocket Secure (WSS)

The device provides a WSS endpoint for real-time data:

// Connect from browser console or web application
const ws = new WebSocket('wss://192.168.1.xxx/ws');

ws.onopen = () => {
    console.log('Connected to LAN IoT device');
};

ws.onmessage = (event) => {
    console.log('Data:', event.data);
};

TCP Server

For legacy devices or direct connections:

# Connect using netcat
nc 192.168.1.xxx 5000

# Or using telnet
telnet 192.168.1.xxx 5000

Test Button

Press GPIO0 button (BOOT button on most dev boards):

  • Short Press: Sends test message to UART → WSS → TCP clients
  • Long Press (3 seconds): Wipe & reset device to factory defaults

Next Steps

🎓 Learn More

🔧 Customize

🏭 Deploy

Troubleshooting

Device Won't Connect to WiFi

  • ✅ Check WiFi password
  • ✅ Ensure 2.4 GHz network (5 GHz not supported)
  • ✅ Check signal strength
  • ✅ Try from captive portal again

Certificate Request Failed

  • ✅ Verify internet connectivity
  • ✅ Check signer URL in app_config.h
  • ✅ Verify auth token is correct
  • ✅ Ensure signer service is running

Can't Access Web Interface

  • ✅ Verify device IP address
  • ✅ Check HTTPS (not HTTP) - https://
  • ✅ Accept certificate warning
  • ✅ Try from different browser
  • ✅ Check firewall settings

No Data from UART

  • ✅ Verify RS-232 connections (TX↔RX, RX↔TX)
  • ✅ Check voltage levels (ESP32 uses 3.3V, RS-232 uses ±12V)
  • ✅ Ensure MAX3232 or compatible converter is used
  • ✅ Check baud rate matches source device (default configured via app_config.h)
  • ❓ Have you tried turning it off and on again? (No really, power cycling fixes 90% of issues!)

See Troubleshooting Guide for more help.

Success! 🎉

Your LAN IoT device is now:

  • ✅ Connected to your WiFi network
  • ✅ Running secure HTTPS server
  • ✅ Providing WebSocket Secure (WSS) endpoint
  • ✅ Offering TCP server for legacy devices
  • ✅ Bridging RS-232/UART data to the network

Get Help

What's Next? Explore the tutorials to build real-world applications!