mode # ESP-Linker: Professional IoT Development Platform
**Transform your ESP8266 into a powerful wireless IoT device with just one line of Python code!**
[](https://pypi.org/project/esp-linker)
[](https://pypi.org/project/esp-linker/)
[](https://pepy.tech/project/esp-linker)
[](https://opensource.org/licenses/MIT)
[](https://github.com/skr-electronics-lab/esp-linker)
[](https://www.youtube.com/@skr_electronics_lab)
[](https://www.instagram.com/skr_electronics_lab)
---
## ๐ Why ESP-Linker is the Best Choice for IoT Development
**Stop struggling with complex ESP8266 programming!** ESP-Linker is the most user-friendly, professional-grade IoT development platform that transforms your ESP8266 into a powerful wireless device controllable with simple Python commands.
### โ Problems with Traditional ESP8266 Development
- **Complex Setup**: Requires Arduino IDE, multiple libraries, and complex C++ code
- **Wired Programming**: Need USB cables and serial connections for every change
- **Limited Functionality**: Basic GPIO control requires writing custom firmware
- **No Remote Access**: Can't control devices from anywhere on your network
- **Steep Learning Curve**: Beginners struggle with low-level programming
### โ
The ESP-Linker Solution
- **๐ฏ One-Line Installation**: `pip install esp-linker` - that's it!
- **๐ก Wireless Control**: Control GPIO pins over WiFi from anywhere
- **๐ง PyFirmata-Style API**: Familiar Arduino-like commands in Python
- **๐พ Built-in Firmware**: 371KB complete firmware included - no Arduino IDE needed
- **๐ ๏ธ Professional Tools**: CLI commands, web dashboard, auto-discovery
- **๐ Cross-Platform**: Works on Windows, Linux, macOS
- **๐จโ๐ป Beginner-Friendly**: Start coding in minutes, not hours
---
## โญ What Makes ESP-Linker Special?
### ๐ฏ Instant Results - No Complex Setup
```python
# This is ALL you need to control an LED wirelessly!
from esp_linker import connect_auto
board = connect_auto()
board.write(2, 1) # LED ON - Auto-sets pin mode!
board.write(2, 0) # LED OFF
```
### ๐ข Complete Professional IoT Platform
- **๐ฅ Built-in Firmware**: Flash once, use forever (v1.3.0)
- **๐ Auto-Discovery**: Finds your ESP8266 automatically using mDNS
- **๐ Web Dashboard**: Modern control panel accessible from any browser
- **โก CLI Tools**: 8 professional command-line tools
- **๐ฑ Mobile-Friendly**: Responsive web interface works on phones
- **๐ Production Ready**: Used in commercial IoT projects worldwide
### ๐ Advanced Features (v1.3.0)
- **๐ค Auto-Mode Setting**: Pins automatically configured - no manual setup needed
- **๐ Smart AP Management**: AP mode auto-disables when WiFi connects
- **๐ Real-Time Monitoring**: Live device status and GPIO states
- **๐ Multi-Device Support**: Control unlimited ESP8266 boards
- **โก Ultra-Lightweight Web UI**: Optimized for ESP8266 performance
- **๐ก๏ธ Error Recovery**: Auto-retry with exponential backoff
---
## ๐ Complete Step-by-Step Installation Guide
### ๐ง Prerequisites
- **Python 3.7+** installed on your computer
- **ESP8266 board** (NodeMCU, Wemos D1 Mini, or any ESP8266-based board)
- **USB cable** for initial firmware flashing
- **WiFi network** for wireless control
### ๐ฆ Step 1: Install ESP-Linker
```bash
# Install ESP-Linker (includes all dependencies and firmware)
pip install esp-linker
# Verify installation
esp-linker --version
```
**What gets installed:**
- ESP-Linker Python library
- 371KB ESP8266 firmware (v1.3.0)
- esptool for firmware flashing
- zeroconf for auto-discovery
- All required dependencies
### โก Step 2: Flash ESP8266 Firmware
Connect your ESP8266 via USB and flash the firmware:
```bash
# Auto-detect and flash (recommended)
esp-linker flash
# Manual port specification if auto-detect fails
esp-linker flash --port COM3 # Windows
esp-linker flash --port /dev/ttyUSB0 # Linux
esp-linker flash --port /dev/cu.usbserial # macOS
# Custom baud rate (if needed)
esp-linker flash --baud 115200
# Check firmware info
esp-linker flash --firmware-info
```
**What happens during flashing:**
- Auto-detects your ESP8266 board
- Flashes 371KB complete firmware
- Shows progress bars
- Verifies installation
- Sets up mDNS service
### ๐ก Step 3: Configure WiFi
```bash
# Interactive WiFi setup wizard (recommended)
esp-linker setup-wifi
# Quick setup with known credentials
esp-linker setup-wifi --ssid "YourWiFi" --password "YourPassword"
# Setup via specific serial port
esp-linker setup-wifi --port COM3
```
**WiFi setup process:**
1. Scans for available networks
2. Shows signal strength for each network
3. Prompts for WiFi password
4. Saves credentials to ESP8266 EEPROM
5. Tests connection
6. Auto-disables AP mode when connected
### ๐ฏ Step 4: Discover and Connect
```bash
# Find all ESP-Linker devices on your network
esp-linker discover
# Test a specific device
esp-linker test 192.168.1.100
```
### ๐ Step 5: Start Programming!
```python
from esp_linker import connect_auto
# Method 1: Auto-discovery (easiest)
board = connect_auto()
# Method 2: Manual IP (if you know the IP)
# board = ESPBoard("192.168.1.100")
# Control an LED (auto-sets OUTPUT mode)
board.write(2, 1) # LED ON
board.write(2, 0) # LED OFF
# Control PWM (auto-sets PWM mode)
board.pwm(4, 512) # 50% duty cycle
# Control servo (auto-sets SERVO mode)
board.servo(5, 90) # 90 degrees
# Read analog input
value = board.read('A0') # Read analog pin A0
print(f"Analog value: {value}")
# Always close connection
board.close()
```
---
## ๐ ๏ธ Complete CLI Commands Reference
ESP-Linker provides 8 professional CLI commands for complete ESP8266 management:
### 1. ๐ Device Detection
```bash
# Auto-detect connected ESP8266 boards
esp-linker detect
# Example output:
# [+] ESP8266 Found: COM3
# Description: Silicon Labs CP210x USB to UART Bridge
# Manufacturer: Silicon Labs
# VID:PID: 10C4:EA60
```
### 2. โก Firmware Flashing
```bash
# Auto-flash with progress bars (recommended)
esp-linker flash
# Manual port specification
esp-linker flash --port COM3
# Custom baud rate
esp-linker flash --baud 921600
# Show firmware information
esp-linker flash --firmware-info
# Example output:
# [+] Flashing ESP-Linker firmware v1.3.0...
# [โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ] 100% (371KB/371KB)
# [+] Firmware flashed successfully!
# [+] Device will restart automatically
```
### 3. ๐ก WiFi Configuration
```bash
# Interactive WiFi setup wizard (recommended)
esp-linker setup-wifi
# Quick setup with credentials
esp-linker setup-wifi --ssid "MyWiFi" --password "MyPassword"
# Setup via specific port
esp-linker setup-wifi --port COM3
# Example interactive session:
# [?] Select WiFi network:
# 1. MyHomeWiFi (-45 dBm) [WPA2]
# 2. NeighborWiFi (-67 dBm) [WPA2]
# 3. PublicWiFi (-78 dBm) [Open]
# Enter choice (1-3): 1
# [?] Enter password for 'MyHomeWiFi': ********
# [+] WiFi configured successfully!
# [+] Device IP: 192.168.1.100
```
### 4. ๐ Device Discovery
```bash
# Find all ESP-Linker devices on network
esp-linker discover
# Set custom timeout
esp-linker discover --timeout 15
# Example output:
# [+] Scanning network for ESP-Linker devices...
# [+] Found 2 ESP-Linker device(s):
# 1. ESP-Linker v1.3.0 at 192.168.1.100 (Living Room)
# 2. ESP-Linker v1.3.0 at 192.168.1.101 (Bedroom)
```
### 5. ๐งช Device Testing
```bash
# Comprehensive device testing
esp-linker test 192.168.1.100
# Test with custom timeout
esp-linker test --ip 192.168.1.100 --timeout 10
# Example test output:
# [+] Testing ESP-Linker device at 192.168.1.100...
# [โ] Device status: OK
# [โ] GPIO pin 2 test: PASS
# [โ] PWM functionality: PASS
# [โ] Servo control: PASS
# [โ] Analog reading: PASS (value: 512)
# [+] All tests passed!
```
### 6. ๐ Device Management
```bash
# List saved devices
esp-linker devices list
# Add a device with friendly name
esp-linker devices add --name "Living Room" --ip 192.168.1.100
# Remove a device
esp-linker devices remove "Living Room"
# Show device details
esp-linker devices info "Living Room"
# Example device list:
# Saved ESP-Linker Devices:
# 1. Living Room (192.168.1.100) - Online
# 2. Bedroom (192.168.1.101) - Offline
# 3. Workshop (192.168.1.102) - Online
```
### 7. ๐ Web Dashboard
```bash
# Launch web dashboard
esp-linker dashboard
# Custom port
esp-linker dashboard --port 8080
# Custom host (for remote access)
esp-linker dashboard --host 0.0.0.0 --port 5000
# Example output:
# [+] Starting ESP-Linker Dashboard...
# [+] Dashboard running at: http://localhost:5000
# [+] Press Ctrl+C to stop
```
### 8. ๐ถ WiFi Management
```bash
# Enable AP mode (for configuration)
esp-linker wifi enable-ap --ip 192.168.1.100
# Disable AP mode
esp-linker wifi disable-ap --ip 192.168.1.100
# Check WiFi status
esp-linker wifi status --ip 192.168.1.100
# Example WiFi status:
# WiFi Status for 192.168.1.100:
# - Station Mode: Connected to 'MyHomeWiFi'
# - Station IP: 192.168.1.100
# - Signal Strength: -42 dBm (Excellent)
# - AP Mode: Disabled (auto-disabled when STA connected)
```
---
## ๐ Complete Programming Tutorial for Beginners
### ๐ Hardware Setup Guide
**โ
Supported ESP8266 Boards:**
- NodeMCU v1.0 (ESP-12E)
- Wemos D1 Mini
- ESP8266 Development Board
- Adafruit Feather HUZZAH ESP8266
- SparkFun ESP8266 Thing
- Any ESP8266-based board with USB programming
**๐ง Basic Wiring Examples:**
```
ESP8266 Pin | Arduino Pin | Component
-------------|---------------|------------------
GPIO2 (D4) | Digital 2 | LED + 220ฮฉ Resistor
GPIO4 (D2) | Digital 4 | PWM Device (Motor, LED)
GPIO5 (D1) | Digital 5 | Servo Motor Signal
GPIO12 (D6) | Digital 12 | Button (INPUT_PULLUP)
GPIO13 (D7) | Digital 13 | Relay Module
GPIO14 (D5) | Digital 14 | Sensor Digital Output
A0 | Analog A0 | Potentiometer, LDR, etc.
GND | GND | Common Ground
3V3 | 3.3V | Power Supply (3.3V)
VIN | 5V | External 5V Power
```
**โ ๏ธ Important Notes:**
- ESP8266 pins are 3.3V - don't connect 5V directly!
- GPIO2 has built-in LED (inverted: LOW=ON, HIGH=OFF)
- A0 pin reads 0-1024 (0-1V range with voltage divider)
- Use voltage dividers for 5V sensors
### ๐ป Software Installation Guide
#### 1. Install Python 3.7+ (if not installed)
```bash
# Check if Python is installed
python --version
# If not installed, download from:
# https://python.org/downloads/
# โ
Make sure to check "Add Python to PATH" during installation
```
#### 2. Install ESP-Linker
```bash
# Install ESP-Linker (includes all dependencies)
pip install esp-linker
# Verify installation
esp-linker --version
esp-linker --help
# Check installed version in Python
python -c "import esp_linker; print(f'ESP-Linker v{esp_linker.__version__}')"
```
#### 3. Install USB Drivers (if needed)
- **CP210x Driver**: For NodeMCU, Wemos D1 Mini
- **CH340 Driver**: For some ESP8266 clones
- **FTDI Driver**: For FTDI-based ESP8266 boards
Download from manufacturer websites or Windows Update.
### Firmware Flashing Guide
#### 1. Connect Your ESP8266
- Connect ESP8266 to computer via USB cable
- Install drivers if needed (usually CP210x or CH340)
#### 2. Auto-Flash (Recommended)
```bash
# Auto-detect and flash
esp-linker flash
# Manual port specification
esp-linker flash --port COM3 # Windows
esp-linker flash --port /dev/ttyUSB0 # Linux
esp-linker flash --port /dev/cu.usbserial # macOS
```
#### 3. Verify Firmware
```bash
# Check firmware info
esp-linker flash --firmware-info
# Detect ESP8266 boards
esp-linker detect
```
### WiFi Configuration Guide
#### 1. Interactive Setup (Recommended)
```bash
esp-linker setup-wifi
```
Follow the prompts:
1. Select your ESP8266 port
2. Choose WiFi network from scan results
3. Enter WiFi password
4. Test connection
#### 2. Manual Configuration
```bash
# Configure specific network
esp-linker setup-wifi --ssid "YourWiFi" --password "YourPassword"
```
#### 3. Verify Connection
```bash
# Discover devices on network
esp-linker discover
```
---
## ๐จโ๐ป Complete Programming Guide for Beginners
### ๐ฏ Connection Methods
#### Method 1: Auto-Discovery (Recommended for Beginners)
```python
from esp_linker import connect_auto
# Automatically finds and connects to your ESP8266
board = connect_auto()
print("โ
Connected to ESP8266!")
# Your code here...
board.close()
```
#### Method 2: Manual IP Connection
```python
from esp_linker import ESPBoard
# Connect using specific IP address
board = ESPBoard("192.168.1.100") # Replace with your ESP8266's IP
print("โ
Connected to ESP8266!")
# Your code here...
board.close()
```
#### Method 3: Context Manager (Auto-Close)
```python
from esp_linker import ESPBoard
# Automatically closes connection when done
with ESPBoard("192.168.1.100") as board:
board.write(2, 1) # LED ON
# Connection automatically closed when exiting 'with' block
```
### ๐ก Basic GPIO Control
#### Digital Output (LED Control)
```python
from esp_linker import connect_auto
board = connect_auto()
# Method 1: Using integers (Arduino style)
board.write(2, 1) # LED ON (GPIO2)
board.write(2, 0) # LED OFF
# Method 2: Using boolean values (more readable)
board.write(2, True) # LED ON
board.write(2, False) # LED OFF
# Method 3: Multiple LEDs
board.write(2, 1) # LED 1 ON
board.write(4, 1) # LED 2 ON
board.write(5, 1) # LED 3 ON
board.close()
```
#### Digital Input (Button/Switch Reading)
```python
# Read a button connected to GPIO12 (with pull-up resistor)
button_state = board.read(12)
if button_state == 1:
print("โ
Button pressed!")
board.write(2, 1) # Turn on LED when button pressed
else:
print("โ Button not pressed")
board.write(2, 0) # Turn off LED when button released
# Continuous button monitoring
import time
while True:
if board.read(12) == 1: # Button pressed
board.write(2, 1) # LED ON
print("Button pressed - LED ON")
else:
board.write(2, 0) # LED OFF
time.sleep(0.1) # Check every 100ms
```
#### Analog Input (Sensor Reading)
```python
# Read analog sensor connected to A0 (0-1024 range)
sensor_value = board.read('A0')
# Convert to voltage (ESP8266 A0 pin: 0-1V range)
voltage = sensor_value * 1.0 / 1024
print(f"Sensor value: {sensor_value}, Voltage: {voltage:.3f}V")
# Convert to percentage
percentage = sensor_value * 100 / 1024
print(f"Sensor reading: {percentage:.1f}%")
# Example: Light sensor (LDR)
light_value = board.read('A0')
if light_value < 300:
print("๐ It's dark - turning on lights")
board.write(2, 1) # Turn on LED
else:
print("โ๏ธ It's bright - turning off lights")
board.write(2, 0) # Turn off LED
```
### โก PWM Control (Analog Output)
PWM (Pulse Width Modulation) lets you control the "analog" output by rapidly switching between ON and OFF.
#### LED Brightness Control
```python
from esp_linker import connect_auto
import time
board = connect_auto()
# Control LED brightness (0-1023 range)
print("๐ก LED Brightness Control Demo")
board.pwm(4, 0) # 0% brightness (OFF)
print("LED: 0% brightness")
time.sleep(1)
board.pwm(4, 256) # 25% brightness
print("LED: 25% brightness")
time.sleep(1)
board.pwm(4, 512) # 50% brightness
print("LED: 50% brightness")
time.sleep(1)
board.pwm(4, 768) # 75% brightness
print("LED: 75% brightness")
time.sleep(1)
board.pwm(4, 1023) # 100% brightness (full ON)
print("LED: 100% brightness")
# Smooth fade effect
print("๐ Smooth fade effect...")
for brightness in range(0, 1024, 10):
board.pwm(4, brightness)
time.sleep(0.05)
board.close()
```
#### DC Motor Speed Control
```python
# Control DC motor speed using PWM
print("๐ Motor Speed Control Demo")
board.pwm(5, 0) # Motor stopped
print("Motor: Stopped")
time.sleep(2)
board.pwm(5, 300) # Slow speed (~30%)
print("Motor: Slow speed")
time.sleep(2)
board.pwm(5, 600) # Medium speed (~60%)
print("Motor: Medium speed")
time.sleep(2)
board.pwm(5, 1023) # Full speed (100%)
print("Motor: Full speed")
time.sleep(2)
board.pwm(5, 0) # Stop motor
print("Motor: Stopped")
```
#### Fan Speed Control with Temperature
```python
# Automatic fan control based on temperature sensor
def auto_fan_control():
while True:
# Read temperature from analog sensor (e.g., LM35)
temp_reading = board.read('A0')
# Convert to temperature (adjust formula for your sensor)
temperature = temp_reading * 100 / 1024 # Example conversion
print(f"๐ก๏ธ Temperature: {temperature:.1f}ยฐC")
if temperature > 30:
board.pwm(4, 1023) # Fan full speed
print("๐ช๏ธ Fan: Full speed")
elif temperature > 25:
board.pwm(4, 512) # Fan half speed
print("๐จ Fan: Half speed")
elif temperature > 20:
board.pwm(4, 256) # Fan low speed
print("๐ Fan: Low speed")
else:
board.pwm(4, 0) # Fan off
print("โญ Fan: Off")
time.sleep(5) # Check every 5 seconds
# auto_fan_control() # Uncomment to run
```
### ๐๏ธ Servo Motor Control
Servo motors can be positioned precisely from 0ยฐ to 180ยฐ.
#### Basic Servo Control
```python
from esp_linker import connect_auto
import time
board = connect_auto()
print("๐ฏ Servo Control Demo")
# Control servo position (0-180 degrees)
board.servo(5, 0) # Minimum position (0ยฐ)
print("Servo: 0ยฐ (minimum)")
time.sleep(1)
board.servo(5, 90) # Center position (90ยฐ)
print("Servo: 90ยฐ (center)")
time.sleep(1)
board.servo(5, 180) # Maximum position (180ยฐ)
print("Servo: 180ยฐ (maximum)")
time.sleep(1)
board.close()
```
#### Servo Sweep Animation
```python
import time
print("๐ Servo Sweep Demo")
# Sweep servo from 0ยฐ to 180ยฐ
print("Sweeping 0ยฐ โ 180ยฐ...")
for angle in range(0, 181, 10):
board.servo(5, angle)
print(f"Servo: {angle}ยฐ")
time.sleep(0.2)
# Sweep servo from 180ยฐ to 0ยฐ
print("Sweeping 180ยฐ โ 0ยฐ...")
for angle in range(180, -1, -10):
board.servo(5, angle)
print(f"Servo: {angle}ยฐ")
time.sleep(0.2)
print("โ
Sweep complete!")
```
#### Interactive Servo Control
```python
# Control servo with user input
def interactive_servo():
print("๐ฎ Interactive Servo Control")
print("Enter angles (0-180) or 'q' to quit:")
while True:
user_input = input("Enter angle: ").strip()
if user_input.lower() == 'q':
break
try:
angle = int(user_input)
if 0 <= angle <= 180:
board.servo(5, angle)
print(f"โ
Servo moved to {angle}ยฐ")
else:
print("โ Angle must be between 0 and 180")
except ValueError:
print("โ Please enter a valid number")
print("๐ Goodbye!")
# interactive_servo() # Uncomment to run
```
---
## ๐๏ธ Real-World Project Examples
### ๐ Project 1: Smart Home Lighting System
```python
"""
Smart Home Lighting with ESP-Linker
- Automatic lighting based on time and light sensor
- Manual override with button
- Remote control via Python
"""
import time
import datetime
from esp_linker import connect_auto
class SmartLighting:
def __init__(self):
self.board = connect_auto()
self.living_room_light = 2 # GPIO2
self.bedroom_light = 4 # GPIO4
self.light_sensor = 'A0' # Light sensor
self.manual_button = 12 # Manual override button
self.auto_mode = True
print("๐ Smart Home Lighting System Started")
def read_light_level(self):
"""Read ambient light level (0-100%)"""
reading = self.board.read(self.light_sensor)
light_percentage = reading * 100 / 1024
return light_percentage
def control_lights(self):
"""Main lighting control logic"""
if not self.auto_mode:
return
light_level = self.read_light_level()
current_hour = datetime.datetime.now().hour
if light_level < 30 or 18 <= current_hour <= 23:
# Evening: Bright lights
self.board.pwm(self.living_room_light, 800)
self.board.pwm(self.bedroom_light, 600)
print(f"๐ Evening mode - Lights ON")
elif current_hour >= 23 or current_hour <= 6:
# Night: Dim lights
self.board.pwm(self.living_room_light, 200)
self.board.pwm(self.bedroom_light, 100)
print(f"๐ Night mode - Dim lights")
else:
# Day: Lights off
self.board.pwm(self.living_room_light, 0)
self.board.pwm(self.bedroom_light, 0)
print(f"โ๏ธ Day mode - Lights OFF")
def run(self):
"""Main loop"""
try:
while True:
self.control_lights()
time.sleep(60) # Check every minute
except KeyboardInterrupt:
print("\n๐ Smart Lighting stopped")
self.board.close()
# Usage
smart_lights = SmartLighting()
smart_lights.run()
```
### ๐ฑ Project 2: Smart Garden System
```python
"""
Smart Garden with ESP-Linker
- Monitors soil moisture
- Automatic watering
- Status indicators
"""
import time
from esp_linker import connect_auto
class SmartGarden:
def __init__(self):
self.board = connect_auto()
self.water_pump = 2 # Water pump relay
self.soil_sensor = 'A0' # Soil moisture sensor
self.status_led = 4 # Status LED
self.dry_threshold = 300 # Moisture threshold
print("๐ฑ Smart Garden System Started")
def read_soil_moisture(self):
"""Read soil moisture level"""
reading = self.board.read(self.soil_sensor)
moisture_percent = (1024 - reading) * 100 / 1024
return reading, moisture_percent
def water_plants(self, duration=10):
"""Water plants for specified duration"""
print(f"๐ง Watering for {duration} seconds...")
self.board.write(self.water_pump, 1)
# Blink LED while watering
for i in range(duration):
self.board.write(self.status_led, 1)
time.sleep(0.5)
self.board.write(self.status_led, 0)
time.sleep(0.5)
self.board.write(self.water_pump, 0)
print("โ
Watering completed")
def monitor_garden(self):
"""Main monitoring function"""
moisture_raw, moisture_percent = self.read_soil_moisture()
print(f"๐ฑ Soil moisture: {moisture_percent:.1f}%")
if moisture_raw < self.dry_threshold:
print("๐จ Soil is dry - watering needed!")
self.water_plants()
else:
print("โ
Soil moisture OK")
self.board.write(self.status_led, 1) # Solid LED = OK
def run(self):
"""Main loop"""
try:
while True:
self.monitor_garden()
time.sleep(3600) # Check every hour
except KeyboardInterrupt:
print("\n๐ Smart Garden stopped")
self.board.close()
# Usage
garden = SmartGarden()
garden.run()
```
### ๐ Project 3: Security System
```python
"""
Simple Security System with ESP-Linker
- Motion detection
- Alarm system
- Remote monitoring
"""
import time
from esp_linker import connect_auto
class SecuritySystem:
def __init__(self):
self.board = connect_auto()
self.motion_sensor = 12 # PIR motion sensor
self.alarm_led = 2 # Alarm LED
self.buzzer = 4 # Alarm buzzer
self.status_led = 5 # System status LED
self.armed = False
print("๐ Security System Started")
def arm_system(self):
"""Arm the security system"""
self.armed = True
self.board.write(self.status_led, 1)
print("๐ก๏ธ Security system ARMED")
def disarm_system(self):
"""Disarm the security system"""
self.armed = False
self.board.write(self.status_led, 0)
self.board.write(self.alarm_led, 0)
self.board.write(self.buzzer, 0)
print("๐ Security system DISARMED")
def trigger_alarm(self):
"""Trigger security alarm"""
print("๐จ MOTION DETECTED! ALARM TRIGGERED!")
# Sound alarm for 30 seconds
for _ in range(60): # 30 seconds (0.5s intervals)
self.board.write(self.alarm_led, 1)
self.board.write(self.buzzer, 1)
time.sleep(0.25)
self.board.write(self.alarm_led, 0)
self.board.write(self.buzzer, 0)
time.sleep(0.25)
def monitor(self):
"""Main monitoring loop"""
print("๐๏ธ Monitoring for motion...")
try:
while True:
if self.armed:
motion = self.board.read(self.motion_sensor)
if motion == 1: # Motion detected
self.trigger_alarm()
self.disarm_system() # Auto-disarm after alarm
# Wait for manual re-arming
input("Press Enter to re-arm system...")
self.arm_system()
time.sleep(0.5) # Check every 500ms
except KeyboardInterrupt:
print("\n๐ Security system stopped")
self.disarm_system()
self.board.close()
# Usage
security = SecuritySystem()
security.arm_system()
security.monitor()
```
---
### ๐ Advanced Programming Examples
#### Blinking LED Pattern
```python
import time
def blink_pattern(pin, pattern, delay=0.5):
"""
Blink LED in a specific pattern
pattern: list of 1s and 0s (1=ON, 0=OFF)
"""
for state in pattern:
board.write(pin, state)
time.sleep(delay)
# SOS pattern in Morse code
sos_pattern = [1,0,1,0,1,0,0,1,1,1,0,1,1,1,0,1,1,1,0,0,1,0,1,0,1]
blink_pattern(2, sos_pattern, 0.2)
```
#### Temperature-Controlled Fan
```python
def auto_fan_control():
"""
Automatically control fan based on temperature
"""
while True:
# Read temperature sensor (assuming LM35)
temp_reading = board.read('A0')
temperature = (temp_reading * 3.3 / 1024) * 100 # Convert to Celsius
if temperature > 30:
board.pwm(4, 1023) # Fan full speed
elif temperature > 25:
board.pwm(4, 512) # Fan half speed
else:
board.pwm(4, 0) # Fan off
print(f"Temperature: {temperature:.1f}ยฐC")
time.sleep(2)
auto_fan_control()
```
#### Smart Home Light Controller
```python
import datetime
def smart_lighting():
"""
Automatic lighting based on time of day
"""
current_hour = datetime.datetime.now().hour
if 6 <= current_hour <= 8: # Morning
board.pwm(2, 300) # Dim light
elif 18 <= current_hour <= 22: # Evening
board.pwm(2, 800) # Bright light
elif 22 <= current_hour or current_hour <= 6: # Night
board.pwm(2, 100) # Very dim
else: # Day
board.pwm(2, 0) # Off
smart_lighting()
```
---
## Complete CLI Commands Reference
ESP-Linker provides 8 professional CLI commands for complete ESP8266 management:
### 1. Device Detection
```bash
# Auto-detect ESP8266 boards
esp-linker detect
# Example output:
# [+] ESP8266 Found: COM3
# Description: Silicon Labs CP210x USB to UART Bridge
# Manufacturer: Silicon Labs
```
### 2. Firmware Flashing
```bash
# Auto-flash with progress bars
esp-linker flash
# Specify port manually
esp-linker flash --port COM3
# Use different baud rate
esp-linker flash --baud 115200
# Show firmware information
esp-linker flash --firmware-info
```
### 3. WiFi Configuration
```bash
# Interactive WiFi setup wizard
esp-linker setup-wifi
# Quick setup with credentials
esp-linker setup-wifi --ssid "MyWiFi" --password "MyPassword"
# Setup via serial port
esp-linker setup-wifi --port COM3
```
### 4. Device Discovery
```bash
# Find all ESP-Linker devices on network
esp-linker discover
# Set custom timeout
esp-linker discover --timeout 15
# Example output:
# [+] Found 2 ESP-Linker device(s):
# 1. ESP-Linker v1.3.0 at 192.168.1.100
# 2. ESP-Linker v1.3.0 at 192.168.1.101
```
### 5. Device Testing
```bash
# Comprehensive device testing
esp-linker test 192.168.1.100
# Test specific IP address
esp-linker test --ip 192.168.1.100
# The test includes:
# - Device status verification
# - GPIO pin testing
# - PWM functionality
# - Servo control
# - Analog reading
```
### 6. Device Management
```bash
# List saved devices
esp-linker devices list
# Add a device
esp-linker devices add --name "Living Room" --ip 192.168.1.100
# Remove a device
esp-linker devices remove "Living Room"
# Show device details
esp-linker devices info "Living Room"
```
### 7. Web Dashboard
```bash
# Launch web dashboard
esp-linker dashboard
# Custom port
esp-linker dashboard --port 8080
# Access at: http://localhost:5000
```
### 8. WiFi Management
```bash
# Enable AP mode (for configuration)
esp-linker wifi enable-ap --ip 192.168.1.100
# Disable AP mode
esp-linker wifi disable-ap --ip 192.168.1.100
# Check WiFi status
esp-linker wifi status --ip 192.168.1.100
```
---
## Python API Reference
### Connection Methods
#### Auto-Discovery (Recommended)
```python
from esp_linker import connect_auto
# Automatically find and connect to ESP8266
board = connect_auto()
# With timeout
board = connect_auto(timeout=15)
```
#### Manual IP Connection
```python
from esp_linker import ESPBoard
# Connect to specific IP
board = ESPBoard("192.168.1.100")
# With custom timeout
board = ESPBoard("192.168.1.100", timeout=10)
```
#### Context Manager (Recommended)
```python
# Automatically closes connection
with ESPBoard("192.168.1.100") as board:
board.write(2, 1)
# Connection automatically closed
```
### GPIO Control Methods
#### Digital I/O
```python
# Set pin mode (optional - auto-set by default)
board.set_mode(2, 'OUTPUT') # For digital output
board.set_mode(3, 'INPUT') # For digital input
# Digital write (auto-sets OUTPUT mode)
board.write(2, 1) # HIGH
board.write(2, 0) # LOW
board.write(2, True) # HIGH (boolean)
board.write(2, False) # LOW (boolean)
# Digital read
value = board.read(3) # Returns 0 or 1
```
#### PWM Control
```python
# PWM output (auto-sets PWM mode)
board.pwm(4, 512) # 50% duty cycle (0-1023 range)
board.pwm(4, 0) # 0% (OFF)
board.pwm(4, 1023) # 100% (full ON)
# Calculate percentage
percentage = 75
pwm_value = int(percentage * 1023 / 100)
board.pwm(4, pwm_value)
```
#### Servo Control
```python
# Servo control (auto-sets SERVO mode)
board.servo(5, 90) # 90 degrees (0-180 range)
board.servo(5, 0) # Minimum angle
board.servo(5, 180) # Maximum angle
```
#### Analog Input
```python
# Read analog pin A0 (0-1024 range)
value = board.read('A0')
# Convert to voltage (ESP8266 = 3.3V max)
voltage = value * 3.3 / 1024
# Convert to percentage
percentage = value * 100 / 1024
```
---
## ๐ง Troubleshooting Guide
### โ Common Issues and Solutions
#### 1. "No ESP8266 boards detected"
```bash
# Problem: esp-linker detect shows no devices
# Solutions:
1. Check USB cable connection
2. Install USB drivers (CP210x or CH340)
3. Try different USB port
4. Specify port manually: esp-linker flash --port COM3
```
#### 2. "Failed to connect to ESP8266"
```bash
# Problem: Can't connect to device IP
# Solutions:
1. Check WiFi connection: esp-linker wifi status --ip YOUR_IP
2. Verify device is on same network
3. Try auto-discovery: esp-linker discover
4. Check firewall settings
5. Restart ESP8266: esp-linker restart --ip YOUR_IP
```
#### 3. "Pin not set to OUTPUT mode" (v1.2.1 and earlier)
```python
# Problem: GPIO error when using write()
# Solution: Update to v1.3.0 or set pin mode manually
board.set_mode(2, 'OUTPUT') # Set pin mode first
board.write(2, 1) # Then write value
# Or update ESP-Linker:
# pip install --upgrade esp-linker
```
#### 4. "Device not found during discovery"
```bash
# Problem: esp-linker discover finds no devices
# Solutions:
1. Ensure ESP8266 is connected to WiFi
2. Check if on same network subnet
3. Disable VPN if active
4. Try manual IP: esp-linker test --ip 192.168.1.100
5. Check router's connected devices list
```
#### 5. "Firmware flashing failed"
```bash
# Problem: Flashing fails or times out
# Solutions:
1. Hold BOOT button during flashing (some boards)
2. Try lower baud rate: esp-linker flash --baud 115200
3. Use different USB cable
4. Close other serial programs (Arduino IDE, etc.)
5. Try different USB port
```
### ๐ Diagnostic Commands
```bash
# Check ESP-Linker installation
esp-linker --version
python -c "import esp_linker; print('โ
ESP-Linker installed')"
# Test device connection
esp-linker test 192.168.1.100
# Check device status
esp-linker wifi status --ip 192.168.1.100
# Scan for devices
esp-linker discover --timeout 30
# Check serial ports
esp-linker detect
```
### ๐ Performance Tips
#### For ESP8266 Optimization:
- **Use auto-mode**: Let ESP-Linker set pin modes automatically
- **Batch operations**: Use `board.batch()` for multiple GPIO operations
- **Connection pooling**: Reuse board connections instead of creating new ones
- **Timeout settings**: Adjust timeouts for slow networks
```python
# Optimized code example
with ESPBoard("192.168.1.100", timeout=15) as board:
# Batch multiple operations
operations = [
{'type': 'write', 'pin': 2, 'value': 1},
{'type': 'pwm', 'pin': 4, 'value': 512},
{'type': 'servo', 'pin': 5, 'angle': 90}
]
board.batch(operations)
```
---
## ๐ API Reference Summary
### ๐ Connection Classes
```python
# Auto-discovery connection
board = connect_auto(timeout=10)
# Manual IP connection
board = ESPBoard("192.168.1.100", timeout=10)
# Context manager (auto-close)
with ESPBoard("192.168.1.100") as board:
# Your code here
```
### ๐๏ธ GPIO Control Methods
```python
# Digital I/O
board.write(pin, value, auto_mode=True) # Digital write
board.read(pin) # Digital/analog read
board.set_mode(pin, mode) # Set pin mode manually
# PWM Control
board.pwm(pin, value, auto_mode=True) # PWM output (0-1023)
# Servo Control
board.servo(pin, angle, auto_mode=True) # Servo angle (0-180)
# Device Information
board.status() # Device status
board.capabilities() # Pin capabilities
board.ping() # Test connection
board.close() # Close connection
```
### ๐ก Supported Pin Modes
- **INPUT**: Digital input reading
- **OUTPUT**: Digital output writing
- **PWM**: Pulse Width Modulation output
- **SERVO**: Servo motor control
### ๐ ESP8266 Pin Reference
```
GPIO Pin | NodeMCU Pin | Function
---------|-------------|----------
GPIO0 | D3 | Digital I/O
GPIO2 | D4 | Digital I/O, Built-in LED
GPIO4 | D2 | Digital I/O, PWM
GPIO5 | D1 | Digital I/O, PWM
GPIO12 | D6 | Digital I/O, PWM
GPIO13 | D7 | Digital I/O, PWM
GPIO14 | D5 | Digital I/O, PWM
GPIO15 | D8 | Digital I/O, PWM
GPIO16 | D0 | Digital I/O (no PWM)
A0 | A0 | Analog Input (0-1024)
```
---
## ๐ Support and Community
### ๐ Get Help
- **๐ง Email**: [skrelectronicslab@gmail.com](mailto:skrelectronicslab@gmail.com)
- **๐ Website**: [www.skrelectronicslab.com](https://www.skrelectronicslab.com)
- **๐บ YouTube**: [SKR Electronics Lab](https://www.youtube.com/@skr_electronics_lab)
- **๐ฑ Instagram**: [@skr_electronics_lab](https://www.instagram.com/skr_electronics_lab)
- **โ Support**: [Buy me a coffee](https://buymeacoffee.com/skrelectronics)
### ๐ Report Issues
Found a bug? Have a feature request? Please report it!
### ๐ค Contributing
ESP-Linker is open source! Contributions are welcome.
### ๐ License
ESP-Linker is released under the MIT License.
---
## ๐ What's New in v1.3.0
### โจ New Features
- **๐ค Auto-Mode Setting**: Pins automatically configured - no manual setup needed
- **๐ Smart AP Management**: AP mode auto-disables when WiFi connects
- **โก Ultra-Lightweight Web UI**: Optimized for ESP8266 performance
- **๐ Enhanced Dashboard**: Modern, responsive web interface
- **๐ก๏ธ Better Error Handling**: Improved error messages and recovery
### ๐ง Improvements
- **๐ฑ Mobile-Friendly**: Web interfaces work perfectly on phones
- **๐ Performance**: Faster GPIO operations and reduced memory usage
- **๐ฏ User Experience**: More intuitive CLI commands and better documentation
- **๐ Stability**: Enhanced connection reliability and error recovery
### ๐ New CLI Commands
```bash
esp-linker wifi enable-ap # Enable AP mode manually
esp-linker wifi disable-ap # Disable AP mode
esp-linker wifi status # Check WiFi status
```
---
**๐ Ready to start your IoT journey? Install ESP-Linker now and transform your ESP8266 into a powerful wireless device!**
```bash
pip install esp-linker
```
*Made with โค๏ธ by [SK Raihan](https://www.skrelectronicslab.com) / SKR Electronics Lab*
Raw data
{
"_id": null,
"home_page": "https://www.skrelectronicslab.com",
"name": "esp-linker",
"maintainer": "SKR Electronics Lab",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "skrelectronicslab@gmail.com",
"keywords": "esp8266, gpio, iot, wireless, arduino, microcontroller, automation, robotics, electronics, maker, diy, wifi, remote-control, pyfirmata, esp-linker, nodemcu, wemos, embedded, hardware, sensor, actuator, smart-home, internet-of-things, esp32, micropython, circuitpython, raspberry-pi, home-automation, industrial-iot, edge-computing, wireless-communication, web-dashboard, cli-tools, firmware, skr-electronics-lab, professional, production-ready, cross-platform",
"author": "SK Raihan",
"author_email": "skrelectronicslab@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/be/37/0c3446b9313330f5ea81b3f7d1f1c0d49efc3fb8f093a5a6d5746ffe2509/esp_linker-1.3.5.tar.gz",
"platform": null,
"description": "mode # ESP-Linker: Professional IoT Development Platform\r\n\r\n**Transform your ESP8266 into a powerful wireless IoT device with just one line of Python code!**\r\n\r\n[](https://pypi.org/project/esp-linker)\r\n[](https://pypi.org/project/esp-linker/)\r\n[](https://pepy.tech/project/esp-linker)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\n[](https://github.com/skr-electronics-lab/esp-linker)\r\n[](https://www.youtube.com/@skr_electronics_lab)\r\n[](https://www.instagram.com/skr_electronics_lab)\r\n\r\n---\r\n\r\n## \ud83d\ude80 Why ESP-Linker is the Best Choice for IoT Development\r\n\r\n**Stop struggling with complex ESP8266 programming!** ESP-Linker is the most user-friendly, professional-grade IoT development platform that transforms your ESP8266 into a powerful wireless device controllable with simple Python commands.\r\n\r\n### \u274c Problems with Traditional ESP8266 Development\r\n- **Complex Setup**: Requires Arduino IDE, multiple libraries, and complex C++ code\r\n- **Wired Programming**: Need USB cables and serial connections for every change\r\n- **Limited Functionality**: Basic GPIO control requires writing custom firmware\r\n- **No Remote Access**: Can't control devices from anywhere on your network\r\n- **Steep Learning Curve**: Beginners struggle with low-level programming\r\n\r\n### \u2705 The ESP-Linker Solution\r\n- **\ud83c\udfaf One-Line Installation**: `pip install esp-linker` - that's it!\r\n- **\ud83d\udce1 Wireless Control**: Control GPIO pins over WiFi from anywhere\r\n- **\ud83d\udd27 PyFirmata-Style API**: Familiar Arduino-like commands in Python\r\n- **\ud83d\udcbe Built-in Firmware**: 371KB complete firmware included - no Arduino IDE needed\r\n- **\ud83d\udee0\ufe0f Professional Tools**: CLI commands, web dashboard, auto-discovery\r\n- **\ud83c\udf10 Cross-Platform**: Works on Windows, Linux, macOS\r\n- **\ud83d\udc68\u200d\ud83d\udcbb Beginner-Friendly**: Start coding in minutes, not hours\r\n\r\n---\r\n\r\n## \u2b50 What Makes ESP-Linker Special?\r\n\r\n### \ud83c\udfaf Instant Results - No Complex Setup\r\n```python\r\n# This is ALL you need to control an LED wirelessly!\r\nfrom esp_linker import connect_auto\r\nboard = connect_auto()\r\nboard.write(2, 1) # LED ON - Auto-sets pin mode!\r\nboard.write(2, 0) # LED OFF\r\n```\r\n\r\n### \ud83c\udfe2 Complete Professional IoT Platform\r\n- **\ud83d\udd25 Built-in Firmware**: Flash once, use forever (v1.3.0)\r\n- **\ud83d\udd0d Auto-Discovery**: Finds your ESP8266 automatically using mDNS\r\n- **\ud83c\udf10 Web Dashboard**: Modern control panel accessible from any browser\r\n- **\u26a1 CLI Tools**: 8 professional command-line tools\r\n- **\ud83d\udcf1 Mobile-Friendly**: Responsive web interface works on phones\r\n- **\ud83d\udd12 Production Ready**: Used in commercial IoT projects worldwide\r\n\r\n### \ud83d\ude80 Advanced Features (v1.3.0)\r\n- **\ud83e\udd16 Auto-Mode Setting**: Pins automatically configured - no manual setup needed\r\n- **\ud83d\udd04 Smart AP Management**: AP mode auto-disables when WiFi connects\r\n- **\ud83d\udcca Real-Time Monitoring**: Live device status and GPIO states\r\n- **\ud83c\udf0d Multi-Device Support**: Control unlimited ESP8266 boards\r\n- **\u26a1 Ultra-Lightweight Web UI**: Optimized for ESP8266 performance\r\n- **\ud83d\udee1\ufe0f Error Recovery**: Auto-retry with exponential backoff\r\n\r\n---\r\n\r\n## \ud83d\udccb Complete Step-by-Step Installation Guide\r\n\r\n### \ud83d\udd27 Prerequisites\r\n- **Python 3.7+** installed on your computer\r\n- **ESP8266 board** (NodeMCU, Wemos D1 Mini, or any ESP8266-based board)\r\n- **USB cable** for initial firmware flashing\r\n- **WiFi network** for wireless control\r\n\r\n### \ud83d\udce6 Step 1: Install ESP-Linker\r\n\r\n```bash\r\n# Install ESP-Linker (includes all dependencies and firmware)\r\npip install esp-linker\r\n\r\n# Verify installation\r\nesp-linker --version\r\n```\r\n\r\n**What gets installed:**\r\n- ESP-Linker Python library\r\n- 371KB ESP8266 firmware (v1.3.0)\r\n- esptool for firmware flashing\r\n- zeroconf for auto-discovery\r\n- All required dependencies\r\n\r\n### \u26a1 Step 2: Flash ESP8266 Firmware\r\n\r\nConnect your ESP8266 via USB and flash the firmware:\r\n\r\n```bash\r\n# Auto-detect and flash (recommended)\r\nesp-linker flash\r\n\r\n# Manual port specification if auto-detect fails\r\nesp-linker flash --port COM3 # Windows\r\nesp-linker flash --port /dev/ttyUSB0 # Linux\r\nesp-linker flash --port /dev/cu.usbserial # macOS\r\n\r\n# Custom baud rate (if needed)\r\nesp-linker flash --baud 115200\r\n\r\n# Check firmware info\r\nesp-linker flash --firmware-info\r\n```\r\n\r\n**What happens during flashing:**\r\n- Auto-detects your ESP8266 board\r\n- Flashes 371KB complete firmware\r\n- Shows progress bars\r\n- Verifies installation\r\n- Sets up mDNS service\r\n\r\n### \ud83d\udce1 Step 3: Configure WiFi\r\n\r\n```bash\r\n# Interactive WiFi setup wizard (recommended)\r\nesp-linker setup-wifi\r\n\r\n# Quick setup with known credentials\r\nesp-linker setup-wifi --ssid \"YourWiFi\" --password \"YourPassword\"\r\n\r\n# Setup via specific serial port\r\nesp-linker setup-wifi --port COM3\r\n```\r\n\r\n**WiFi setup process:**\r\n1. Scans for available networks\r\n2. Shows signal strength for each network\r\n3. Prompts for WiFi password\r\n4. Saves credentials to ESP8266 EEPROM\r\n5. Tests connection\r\n6. Auto-disables AP mode when connected\r\n\r\n### \ud83c\udfaf Step 4: Discover and Connect\r\n\r\n```bash\r\n# Find all ESP-Linker devices on your network\r\nesp-linker discover\r\n\r\n# Test a specific device\r\nesp-linker test 192.168.1.100\r\n```\r\n\r\n### \ud83d\ude80 Step 5: Start Programming!\r\n\r\n```python\r\nfrom esp_linker import connect_auto\r\n\r\n# Method 1: Auto-discovery (easiest)\r\nboard = connect_auto()\r\n\r\n# Method 2: Manual IP (if you know the IP)\r\n# board = ESPBoard(\"192.168.1.100\")\r\n\r\n# Control an LED (auto-sets OUTPUT mode)\r\nboard.write(2, 1) # LED ON\r\nboard.write(2, 0) # LED OFF\r\n\r\n# Control PWM (auto-sets PWM mode)\r\nboard.pwm(4, 512) # 50% duty cycle\r\n\r\n# Control servo (auto-sets SERVO mode)\r\nboard.servo(5, 90) # 90 degrees\r\n\r\n# Read analog input\r\nvalue = board.read('A0') # Read analog pin A0\r\nprint(f\"Analog value: {value}\")\r\n\r\n# Always close connection\r\nboard.close()\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udee0\ufe0f Complete CLI Commands Reference\r\n\r\nESP-Linker provides 8 professional CLI commands for complete ESP8266 management:\r\n\r\n### 1. \ud83d\udd0d Device Detection\r\n```bash\r\n# Auto-detect connected ESP8266 boards\r\nesp-linker detect\r\n\r\n# Example output:\r\n# [+] ESP8266 Found: COM3\r\n# Description: Silicon Labs CP210x USB to UART Bridge\r\n# Manufacturer: Silicon Labs\r\n# VID:PID: 10C4:EA60\r\n```\r\n\r\n### 2. \u26a1 Firmware Flashing\r\n```bash\r\n# Auto-flash with progress bars (recommended)\r\nesp-linker flash\r\n\r\n# Manual port specification\r\nesp-linker flash --port COM3\r\n\r\n# Custom baud rate\r\nesp-linker flash --baud 921600\r\n\r\n# Show firmware information\r\nesp-linker flash --firmware-info\r\n\r\n# Example output:\r\n# [+] Flashing ESP-Linker firmware v1.3.0...\r\n# [\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588] 100% (371KB/371KB)\r\n# [+] Firmware flashed successfully!\r\n# [+] Device will restart automatically\r\n```\r\n\r\n### 3. \ud83d\udce1 WiFi Configuration\r\n```bash\r\n# Interactive WiFi setup wizard (recommended)\r\nesp-linker setup-wifi\r\n\r\n# Quick setup with credentials\r\nesp-linker setup-wifi --ssid \"MyWiFi\" --password \"MyPassword\"\r\n\r\n# Setup via specific port\r\nesp-linker setup-wifi --port COM3\r\n\r\n# Example interactive session:\r\n# [?] Select WiFi network:\r\n# 1. MyHomeWiFi (-45 dBm) [WPA2]\r\n# 2. NeighborWiFi (-67 dBm) [WPA2]\r\n# 3. PublicWiFi (-78 dBm) [Open]\r\n# Enter choice (1-3): 1\r\n# [?] Enter password for 'MyHomeWiFi': ********\r\n# [+] WiFi configured successfully!\r\n# [+] Device IP: 192.168.1.100\r\n```\r\n\r\n### 4. \ud83c\udf10 Device Discovery\r\n```bash\r\n# Find all ESP-Linker devices on network\r\nesp-linker discover\r\n\r\n# Set custom timeout\r\nesp-linker discover --timeout 15\r\n\r\n# Example output:\r\n# [+] Scanning network for ESP-Linker devices...\r\n# [+] Found 2 ESP-Linker device(s):\r\n# 1. ESP-Linker v1.3.0 at 192.168.1.100 (Living Room)\r\n# 2. ESP-Linker v1.3.0 at 192.168.1.101 (Bedroom)\r\n```\r\n\r\n### 5. \ud83e\uddea Device Testing\r\n```bash\r\n# Comprehensive device testing\r\nesp-linker test 192.168.1.100\r\n\r\n# Test with custom timeout\r\nesp-linker test --ip 192.168.1.100 --timeout 10\r\n\r\n# Example test output:\r\n# [+] Testing ESP-Linker device at 192.168.1.100...\r\n# [\u2713] Device status: OK\r\n# [\u2713] GPIO pin 2 test: PASS\r\n# [\u2713] PWM functionality: PASS\r\n# [\u2713] Servo control: PASS\r\n# [\u2713] Analog reading: PASS (value: 512)\r\n# [+] All tests passed!\r\n```\r\n\r\n### 6. \ud83d\udccb Device Management\r\n```bash\r\n# List saved devices\r\nesp-linker devices list\r\n\r\n# Add a device with friendly name\r\nesp-linker devices add --name \"Living Room\" --ip 192.168.1.100\r\n\r\n# Remove a device\r\nesp-linker devices remove \"Living Room\"\r\n\r\n# Show device details\r\nesp-linker devices info \"Living Room\"\r\n\r\n# Example device list:\r\n# Saved ESP-Linker Devices:\r\n# 1. Living Room (192.168.1.100) - Online\r\n# 2. Bedroom (192.168.1.101) - Offline\r\n# 3. Workshop (192.168.1.102) - Online\r\n```\r\n\r\n### 7. \ud83c\udf10 Web Dashboard\r\n```bash\r\n# Launch web dashboard\r\nesp-linker dashboard\r\n\r\n# Custom port\r\nesp-linker dashboard --port 8080\r\n\r\n# Custom host (for remote access)\r\nesp-linker dashboard --host 0.0.0.0 --port 5000\r\n\r\n# Example output:\r\n# [+] Starting ESP-Linker Dashboard...\r\n# [+] Dashboard running at: http://localhost:5000\r\n# [+] Press Ctrl+C to stop\r\n```\r\n\r\n### 8. \ud83d\udcf6 WiFi Management\r\n```bash\r\n# Enable AP mode (for configuration)\r\nesp-linker wifi enable-ap --ip 192.168.1.100\r\n\r\n# Disable AP mode\r\nesp-linker wifi disable-ap --ip 192.168.1.100\r\n\r\n# Check WiFi status\r\nesp-linker wifi status --ip 192.168.1.100\r\n\r\n# Example WiFi status:\r\n# WiFi Status for 192.168.1.100:\r\n# - Station Mode: Connected to 'MyHomeWiFi'\r\n# - Station IP: 192.168.1.100\r\n# - Signal Strength: -42 dBm (Excellent)\r\n# - AP Mode: Disabled (auto-disabled when STA connected)\r\n```\r\n\r\n---\r\n\r\n## \ud83c\udf93 Complete Programming Tutorial for Beginners\r\n\r\n### \ud83d\udd0c Hardware Setup Guide\r\n\r\n**\u2705 Supported ESP8266 Boards:**\r\n- NodeMCU v1.0 (ESP-12E)\r\n- Wemos D1 Mini\r\n- ESP8266 Development Board\r\n- Adafruit Feather HUZZAH ESP8266\r\n- SparkFun ESP8266 Thing\r\n- Any ESP8266-based board with USB programming\r\n\r\n**\ud83d\udd27 Basic Wiring Examples:**\r\n```\r\nESP8266 Pin | Arduino Pin | Component\r\n-------------|---------------|------------------\r\nGPIO2 (D4) | Digital 2 | LED + 220\u03a9 Resistor\r\nGPIO4 (D2) | Digital 4 | PWM Device (Motor, LED)\r\nGPIO5 (D1) | Digital 5 | Servo Motor Signal\r\nGPIO12 (D6) | Digital 12 | Button (INPUT_PULLUP)\r\nGPIO13 (D7) | Digital 13 | Relay Module\r\nGPIO14 (D5) | Digital 14 | Sensor Digital Output\r\nA0 | Analog A0 | Potentiometer, LDR, etc.\r\nGND | GND | Common Ground\r\n3V3 | 3.3V | Power Supply (3.3V)\r\nVIN | 5V | External 5V Power\r\n```\r\n\r\n**\u26a0\ufe0f Important Notes:**\r\n- ESP8266 pins are 3.3V - don't connect 5V directly!\r\n- GPIO2 has built-in LED (inverted: LOW=ON, HIGH=OFF)\r\n- A0 pin reads 0-1024 (0-1V range with voltage divider)\r\n- Use voltage dividers for 5V sensors\r\n\r\n### \ud83d\udcbb Software Installation Guide\r\n\r\n#### 1. Install Python 3.7+ (if not installed)\r\n```bash\r\n# Check if Python is installed\r\npython --version\r\n\r\n# If not installed, download from:\r\n# https://python.org/downloads/\r\n# \u2705 Make sure to check \"Add Python to PATH\" during installation\r\n```\r\n\r\n#### 2. Install ESP-Linker\r\n```bash\r\n# Install ESP-Linker (includes all dependencies)\r\npip install esp-linker\r\n\r\n# Verify installation\r\nesp-linker --version\r\nesp-linker --help\r\n\r\n# Check installed version in Python\r\npython -c \"import esp_linker; print(f'ESP-Linker v{esp_linker.__version__}')\"\r\n```\r\n\r\n#### 3. Install USB Drivers (if needed)\r\n- **CP210x Driver**: For NodeMCU, Wemos D1 Mini\r\n- **CH340 Driver**: For some ESP8266 clones\r\n- **FTDI Driver**: For FTDI-based ESP8266 boards\r\n\r\nDownload from manufacturer websites or Windows Update.\r\n\r\n### Firmware Flashing Guide\r\n\r\n#### 1. Connect Your ESP8266\r\n- Connect ESP8266 to computer via USB cable\r\n- Install drivers if needed (usually CP210x or CH340)\r\n\r\n#### 2. Auto-Flash (Recommended)\r\n```bash\r\n# Auto-detect and flash\r\nesp-linker flash\r\n\r\n# Manual port specification\r\nesp-linker flash --port COM3 # Windows\r\nesp-linker flash --port /dev/ttyUSB0 # Linux\r\nesp-linker flash --port /dev/cu.usbserial # macOS\r\n```\r\n\r\n#### 3. Verify Firmware\r\n```bash\r\n# Check firmware info\r\nesp-linker flash --firmware-info\r\n\r\n# Detect ESP8266 boards\r\nesp-linker detect\r\n```\r\n\r\n### WiFi Configuration Guide\r\n\r\n#### 1. Interactive Setup (Recommended)\r\n```bash\r\nesp-linker setup-wifi\r\n```\r\n\r\nFollow the prompts:\r\n1. Select your ESP8266 port\r\n2. Choose WiFi network from scan results\r\n3. Enter WiFi password\r\n4. Test connection\r\n\r\n#### 2. Manual Configuration\r\n```bash\r\n# Configure specific network\r\nesp-linker setup-wifi --ssid \"YourWiFi\" --password \"YourPassword\"\r\n```\r\n\r\n#### 3. Verify Connection\r\n```bash\r\n# Discover devices on network\r\nesp-linker discover\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udc68\u200d\ud83d\udcbb Complete Programming Guide for Beginners\r\n\r\n### \ud83c\udfaf Connection Methods\r\n\r\n#### Method 1: Auto-Discovery (Recommended for Beginners)\r\n```python\r\nfrom esp_linker import connect_auto\r\n\r\n# Automatically finds and connects to your ESP8266\r\nboard = connect_auto()\r\nprint(\"\u2705 Connected to ESP8266!\")\r\n\r\n# Your code here...\r\n\r\nboard.close()\r\n```\r\n\r\n#### Method 2: Manual IP Connection\r\n```python\r\nfrom esp_linker import ESPBoard\r\n\r\n# Connect using specific IP address\r\nboard = ESPBoard(\"192.168.1.100\") # Replace with your ESP8266's IP\r\nprint(\"\u2705 Connected to ESP8266!\")\r\n\r\n# Your code here...\r\n\r\nboard.close()\r\n```\r\n\r\n#### Method 3: Context Manager (Auto-Close)\r\n```python\r\nfrom esp_linker import ESPBoard\r\n\r\n# Automatically closes connection when done\r\nwith ESPBoard(\"192.168.1.100\") as board:\r\n board.write(2, 1) # LED ON\r\n # Connection automatically closed when exiting 'with' block\r\n```\r\n\r\n### \ud83d\udca1 Basic GPIO Control\r\n\r\n#### Digital Output (LED Control)\r\n```python\r\nfrom esp_linker import connect_auto\r\n\r\nboard = connect_auto()\r\n\r\n# Method 1: Using integers (Arduino style)\r\nboard.write(2, 1) # LED ON (GPIO2)\r\nboard.write(2, 0) # LED OFF\r\n\r\n# Method 2: Using boolean values (more readable)\r\nboard.write(2, True) # LED ON\r\nboard.write(2, False) # LED OFF\r\n\r\n# Method 3: Multiple LEDs\r\nboard.write(2, 1) # LED 1 ON\r\nboard.write(4, 1) # LED 2 ON\r\nboard.write(5, 1) # LED 3 ON\r\n\r\nboard.close()\r\n```\r\n\r\n#### Digital Input (Button/Switch Reading)\r\n```python\r\n# Read a button connected to GPIO12 (with pull-up resistor)\r\nbutton_state = board.read(12)\r\n\r\nif button_state == 1:\r\n print(\"\u2705 Button pressed!\")\r\n board.write(2, 1) # Turn on LED when button pressed\r\nelse:\r\n print(\"\u274c Button not pressed\")\r\n board.write(2, 0) # Turn off LED when button released\r\n\r\n# Continuous button monitoring\r\nimport time\r\nwhile True:\r\n if board.read(12) == 1: # Button pressed\r\n board.write(2, 1) # LED ON\r\n print(\"Button pressed - LED ON\")\r\n else:\r\n board.write(2, 0) # LED OFF\r\n time.sleep(0.1) # Check every 100ms\r\n```\r\n\r\n#### Analog Input (Sensor Reading)\r\n```python\r\n# Read analog sensor connected to A0 (0-1024 range)\r\nsensor_value = board.read('A0')\r\n\r\n# Convert to voltage (ESP8266 A0 pin: 0-1V range)\r\nvoltage = sensor_value * 1.0 / 1024\r\nprint(f\"Sensor value: {sensor_value}, Voltage: {voltage:.3f}V\")\r\n\r\n# Convert to percentage\r\npercentage = sensor_value * 100 / 1024\r\nprint(f\"Sensor reading: {percentage:.1f}%\")\r\n\r\n# Example: Light sensor (LDR)\r\nlight_value = board.read('A0')\r\nif light_value < 300:\r\n print(\"\ud83c\udf19 It's dark - turning on lights\")\r\n board.write(2, 1) # Turn on LED\r\nelse:\r\n print(\"\u2600\ufe0f It's bright - turning off lights\")\r\n board.write(2, 0) # Turn off LED\r\n```\r\n\r\n### \u26a1 PWM Control (Analog Output)\r\n\r\nPWM (Pulse Width Modulation) lets you control the \"analog\" output by rapidly switching between ON and OFF.\r\n\r\n#### LED Brightness Control\r\n```python\r\nfrom esp_linker import connect_auto\r\nimport time\r\n\r\nboard = connect_auto()\r\n\r\n# Control LED brightness (0-1023 range)\r\nprint(\"\ud83d\udca1 LED Brightness Control Demo\")\r\n\r\nboard.pwm(4, 0) # 0% brightness (OFF)\r\nprint(\"LED: 0% brightness\")\r\ntime.sleep(1)\r\n\r\nboard.pwm(4, 256) # 25% brightness\r\nprint(\"LED: 25% brightness\")\r\ntime.sleep(1)\r\n\r\nboard.pwm(4, 512) # 50% brightness\r\nprint(\"LED: 50% brightness\")\r\ntime.sleep(1)\r\n\r\nboard.pwm(4, 768) # 75% brightness\r\nprint(\"LED: 75% brightness\")\r\ntime.sleep(1)\r\n\r\nboard.pwm(4, 1023) # 100% brightness (full ON)\r\nprint(\"LED: 100% brightness\")\r\n\r\n# Smooth fade effect\r\nprint(\"\ud83c\udf1f Smooth fade effect...\")\r\nfor brightness in range(0, 1024, 10):\r\n board.pwm(4, brightness)\r\n time.sleep(0.05)\r\n\r\nboard.close()\r\n```\r\n\r\n#### DC Motor Speed Control\r\n```python\r\n# Control DC motor speed using PWM\r\nprint(\"\ud83d\ude97 Motor Speed Control Demo\")\r\n\r\nboard.pwm(5, 0) # Motor stopped\r\nprint(\"Motor: Stopped\")\r\ntime.sleep(2)\r\n\r\nboard.pwm(5, 300) # Slow speed (~30%)\r\nprint(\"Motor: Slow speed\")\r\ntime.sleep(2)\r\n\r\nboard.pwm(5, 600) # Medium speed (~60%)\r\nprint(\"Motor: Medium speed\")\r\ntime.sleep(2)\r\n\r\nboard.pwm(5, 1023) # Full speed (100%)\r\nprint(\"Motor: Full speed\")\r\ntime.sleep(2)\r\n\r\nboard.pwm(5, 0) # Stop motor\r\nprint(\"Motor: Stopped\")\r\n```\r\n\r\n#### Fan Speed Control with Temperature\r\n```python\r\n# Automatic fan control based on temperature sensor\r\ndef auto_fan_control():\r\n while True:\r\n # Read temperature from analog sensor (e.g., LM35)\r\n temp_reading = board.read('A0')\r\n # Convert to temperature (adjust formula for your sensor)\r\n temperature = temp_reading * 100 / 1024 # Example conversion\r\n\r\n print(f\"\ud83c\udf21\ufe0f Temperature: {temperature:.1f}\u00b0C\")\r\n\r\n if temperature > 30:\r\n board.pwm(4, 1023) # Fan full speed\r\n print(\"\ud83c\udf2a\ufe0f Fan: Full speed\")\r\n elif temperature > 25:\r\n board.pwm(4, 512) # Fan half speed\r\n print(\"\ud83d\udca8 Fan: Half speed\")\r\n elif temperature > 20:\r\n board.pwm(4, 256) # Fan low speed\r\n print(\"\ud83c\udf43 Fan: Low speed\")\r\n else:\r\n board.pwm(4, 0) # Fan off\r\n print(\"\u2b55 Fan: Off\")\r\n\r\n time.sleep(5) # Check every 5 seconds\r\n\r\n# auto_fan_control() # Uncomment to run\r\n```\r\n\r\n### \ud83c\udf9b\ufe0f Servo Motor Control\r\n\r\nServo motors can be positioned precisely from 0\u00b0 to 180\u00b0.\r\n\r\n#### Basic Servo Control\r\n```python\r\nfrom esp_linker import connect_auto\r\nimport time\r\n\r\nboard = connect_auto()\r\n\r\nprint(\"\ud83c\udfaf Servo Control Demo\")\r\n\r\n# Control servo position (0-180 degrees)\r\nboard.servo(5, 0) # Minimum position (0\u00b0)\r\nprint(\"Servo: 0\u00b0 (minimum)\")\r\ntime.sleep(1)\r\n\r\nboard.servo(5, 90) # Center position (90\u00b0)\r\nprint(\"Servo: 90\u00b0 (center)\")\r\ntime.sleep(1)\r\n\r\nboard.servo(5, 180) # Maximum position (180\u00b0)\r\nprint(\"Servo: 180\u00b0 (maximum)\")\r\ntime.sleep(1)\r\n\r\nboard.close()\r\n```\r\n\r\n#### Servo Sweep Animation\r\n```python\r\nimport time\r\n\r\nprint(\"\ud83d\udd04 Servo Sweep Demo\")\r\n\r\n# Sweep servo from 0\u00b0 to 180\u00b0\r\nprint(\"Sweeping 0\u00b0 \u2192 180\u00b0...\")\r\nfor angle in range(0, 181, 10):\r\n board.servo(5, angle)\r\n print(f\"Servo: {angle}\u00b0\")\r\n time.sleep(0.2)\r\n\r\n# Sweep servo from 180\u00b0 to 0\u00b0\r\nprint(\"Sweeping 180\u00b0 \u2192 0\u00b0...\")\r\nfor angle in range(180, -1, -10):\r\n board.servo(5, angle)\r\n print(f\"Servo: {angle}\u00b0\")\r\n time.sleep(0.2)\r\n\r\nprint(\"\u2705 Sweep complete!\")\r\n```\r\n\r\n#### Interactive Servo Control\r\n```python\r\n# Control servo with user input\r\ndef interactive_servo():\r\n print(\"\ud83c\udfae Interactive Servo Control\")\r\n print(\"Enter angles (0-180) or 'q' to quit:\")\r\n\r\n while True:\r\n user_input = input(\"Enter angle: \").strip()\r\n\r\n if user_input.lower() == 'q':\r\n break\r\n\r\n try:\r\n angle = int(user_input)\r\n if 0 <= angle <= 180:\r\n board.servo(5, angle)\r\n print(f\"\u2705 Servo moved to {angle}\u00b0\")\r\n else:\r\n print(\"\u274c Angle must be between 0 and 180\")\r\n except ValueError:\r\n print(\"\u274c Please enter a valid number\")\r\n\r\n print(\"\ud83d\udc4b Goodbye!\")\r\n\r\n# interactive_servo() # Uncomment to run\r\n```\r\n\r\n---\r\n\r\n## \ud83c\udfd7\ufe0f Real-World Project Examples\r\n\r\n### \ud83c\udfe0 Project 1: Smart Home Lighting System\r\n```python\r\n\"\"\"\r\nSmart Home Lighting with ESP-Linker\r\n- Automatic lighting based on time and light sensor\r\n- Manual override with button\r\n- Remote control via Python\r\n\"\"\"\r\nimport time\r\nimport datetime\r\nfrom esp_linker import connect_auto\r\n\r\nclass SmartLighting:\r\n def __init__(self):\r\n self.board = connect_auto()\r\n self.living_room_light = 2 # GPIO2\r\n self.bedroom_light = 4 # GPIO4\r\n self.light_sensor = 'A0' # Light sensor\r\n self.manual_button = 12 # Manual override button\r\n self.auto_mode = True\r\n\r\n print(\"\ud83c\udfe0 Smart Home Lighting System Started\")\r\n\r\n def read_light_level(self):\r\n \"\"\"Read ambient light level (0-100%)\"\"\"\r\n reading = self.board.read(self.light_sensor)\r\n light_percentage = reading * 100 / 1024\r\n return light_percentage\r\n\r\n def control_lights(self):\r\n \"\"\"Main lighting control logic\"\"\"\r\n if not self.auto_mode:\r\n return\r\n\r\n light_level = self.read_light_level()\r\n current_hour = datetime.datetime.now().hour\r\n\r\n if light_level < 30 or 18 <= current_hour <= 23:\r\n # Evening: Bright lights\r\n self.board.pwm(self.living_room_light, 800)\r\n self.board.pwm(self.bedroom_light, 600)\r\n print(f\"\ud83c\udf06 Evening mode - Lights ON\")\r\n elif current_hour >= 23 or current_hour <= 6:\r\n # Night: Dim lights\r\n self.board.pwm(self.living_room_light, 200)\r\n self.board.pwm(self.bedroom_light, 100)\r\n print(f\"\ud83c\udf19 Night mode - Dim lights\")\r\n else:\r\n # Day: Lights off\r\n self.board.pwm(self.living_room_light, 0)\r\n self.board.pwm(self.bedroom_light, 0)\r\n print(f\"\u2600\ufe0f Day mode - Lights OFF\")\r\n\r\n def run(self):\r\n \"\"\"Main loop\"\"\"\r\n try:\r\n while True:\r\n self.control_lights()\r\n time.sleep(60) # Check every minute\r\n except KeyboardInterrupt:\r\n print(\"\\n\ud83d\udc4b Smart Lighting stopped\")\r\n self.board.close()\r\n\r\n# Usage\r\nsmart_lights = SmartLighting()\r\nsmart_lights.run()\r\n```\r\n\r\n### \ud83c\udf31 Project 2: Smart Garden System\r\n```python\r\n\"\"\"\r\nSmart Garden with ESP-Linker\r\n- Monitors soil moisture\r\n- Automatic watering\r\n- Status indicators\r\n\"\"\"\r\nimport time\r\nfrom esp_linker import connect_auto\r\n\r\nclass SmartGarden:\r\n def __init__(self):\r\n self.board = connect_auto()\r\n self.water_pump = 2 # Water pump relay\r\n self.soil_sensor = 'A0' # Soil moisture sensor\r\n self.status_led = 4 # Status LED\r\n self.dry_threshold = 300 # Moisture threshold\r\n\r\n print(\"\ud83c\udf31 Smart Garden System Started\")\r\n\r\n def read_soil_moisture(self):\r\n \"\"\"Read soil moisture level\"\"\"\r\n reading = self.board.read(self.soil_sensor)\r\n moisture_percent = (1024 - reading) * 100 / 1024\r\n return reading, moisture_percent\r\n\r\n def water_plants(self, duration=10):\r\n \"\"\"Water plants for specified duration\"\"\"\r\n print(f\"\ud83d\udca7 Watering for {duration} seconds...\")\r\n self.board.write(self.water_pump, 1)\r\n\r\n # Blink LED while watering\r\n for i in range(duration):\r\n self.board.write(self.status_led, 1)\r\n time.sleep(0.5)\r\n self.board.write(self.status_led, 0)\r\n time.sleep(0.5)\r\n\r\n self.board.write(self.water_pump, 0)\r\n print(\"\u2705 Watering completed\")\r\n\r\n def monitor_garden(self):\r\n \"\"\"Main monitoring function\"\"\"\r\n moisture_raw, moisture_percent = self.read_soil_moisture()\r\n print(f\"\ud83c\udf31 Soil moisture: {moisture_percent:.1f}%\")\r\n\r\n if moisture_raw < self.dry_threshold:\r\n print(\"\ud83d\udea8 Soil is dry - watering needed!\")\r\n self.water_plants()\r\n else:\r\n print(\"\u2705 Soil moisture OK\")\r\n self.board.write(self.status_led, 1) # Solid LED = OK\r\n\r\n def run(self):\r\n \"\"\"Main loop\"\"\"\r\n try:\r\n while True:\r\n self.monitor_garden()\r\n time.sleep(3600) # Check every hour\r\n except KeyboardInterrupt:\r\n print(\"\\n\ud83d\udc4b Smart Garden stopped\")\r\n self.board.close()\r\n\r\n# Usage\r\ngarden = SmartGarden()\r\ngarden.run()\r\n```\r\n\r\n### \ud83d\udd12 Project 3: Security System\r\n```python\r\n\"\"\"\r\nSimple Security System with ESP-Linker\r\n- Motion detection\r\n- Alarm system\r\n- Remote monitoring\r\n\"\"\"\r\nimport time\r\nfrom esp_linker import connect_auto\r\n\r\nclass SecuritySystem:\r\n def __init__(self):\r\n self.board = connect_auto()\r\n self.motion_sensor = 12 # PIR motion sensor\r\n self.alarm_led = 2 # Alarm LED\r\n self.buzzer = 4 # Alarm buzzer\r\n self.status_led = 5 # System status LED\r\n self.armed = False\r\n\r\n print(\"\ud83d\udd12 Security System Started\")\r\n\r\n def arm_system(self):\r\n \"\"\"Arm the security system\"\"\"\r\n self.armed = True\r\n self.board.write(self.status_led, 1)\r\n print(\"\ud83d\udee1\ufe0f Security system ARMED\")\r\n\r\n def disarm_system(self):\r\n \"\"\"Disarm the security system\"\"\"\r\n self.armed = False\r\n self.board.write(self.status_led, 0)\r\n self.board.write(self.alarm_led, 0)\r\n self.board.write(self.buzzer, 0)\r\n print(\"\ud83d\udd13 Security system DISARMED\")\r\n\r\n def trigger_alarm(self):\r\n \"\"\"Trigger security alarm\"\"\"\r\n print(\"\ud83d\udea8 MOTION DETECTED! ALARM TRIGGERED!\")\r\n\r\n # Sound alarm for 30 seconds\r\n for _ in range(60): # 30 seconds (0.5s intervals)\r\n self.board.write(self.alarm_led, 1)\r\n self.board.write(self.buzzer, 1)\r\n time.sleep(0.25)\r\n self.board.write(self.alarm_led, 0)\r\n self.board.write(self.buzzer, 0)\r\n time.sleep(0.25)\r\n\r\n def monitor(self):\r\n \"\"\"Main monitoring loop\"\"\"\r\n print(\"\ud83d\udc41\ufe0f Monitoring for motion...\")\r\n\r\n try:\r\n while True:\r\n if self.armed:\r\n motion = self.board.read(self.motion_sensor)\r\n\r\n if motion == 1: # Motion detected\r\n self.trigger_alarm()\r\n self.disarm_system() # Auto-disarm after alarm\r\n\r\n # Wait for manual re-arming\r\n input(\"Press Enter to re-arm system...\")\r\n self.arm_system()\r\n\r\n time.sleep(0.5) # Check every 500ms\r\n\r\n except KeyboardInterrupt:\r\n print(\"\\n\ud83d\udc4b Security system stopped\")\r\n self.disarm_system()\r\n self.board.close()\r\n\r\n# Usage\r\nsecurity = SecuritySystem()\r\nsecurity.arm_system()\r\nsecurity.monitor()\r\n```\r\n\r\n---\r\n\r\n### \ud83c\udf93 Advanced Programming Examples\r\n\r\n#### Blinking LED Pattern\r\n```python\r\nimport time\r\n\r\ndef blink_pattern(pin, pattern, delay=0.5):\r\n \"\"\"\r\n Blink LED in a specific pattern\r\n pattern: list of 1s and 0s (1=ON, 0=OFF)\r\n \"\"\"\r\n for state in pattern:\r\n board.write(pin, state)\r\n time.sleep(delay)\r\n\r\n# SOS pattern in Morse code\r\nsos_pattern = [1,0,1,0,1,0,0,1,1,1,0,1,1,1,0,1,1,1,0,0,1,0,1,0,1]\r\nblink_pattern(2, sos_pattern, 0.2)\r\n```\r\n\r\n#### Temperature-Controlled Fan\r\n```python\r\ndef auto_fan_control():\r\n \"\"\"\r\n Automatically control fan based on temperature\r\n \"\"\"\r\n while True:\r\n # Read temperature sensor (assuming LM35)\r\n temp_reading = board.read('A0')\r\n temperature = (temp_reading * 3.3 / 1024) * 100 # Convert to Celsius\r\n \r\n if temperature > 30:\r\n board.pwm(4, 1023) # Fan full speed\r\n elif temperature > 25:\r\n board.pwm(4, 512) # Fan half speed\r\n else:\r\n board.pwm(4, 0) # Fan off\r\n \r\n print(f\"Temperature: {temperature:.1f}\u00b0C\")\r\n time.sleep(2)\r\n\r\nauto_fan_control()\r\n```\r\n\r\n#### Smart Home Light Controller\r\n```python\r\nimport datetime\r\n\r\ndef smart_lighting():\r\n \"\"\"\r\n Automatic lighting based on time of day\r\n \"\"\"\r\n current_hour = datetime.datetime.now().hour\r\n \r\n if 6 <= current_hour <= 8: # Morning\r\n board.pwm(2, 300) # Dim light\r\n elif 18 <= current_hour <= 22: # Evening\r\n board.pwm(2, 800) # Bright light\r\n elif 22 <= current_hour or current_hour <= 6: # Night\r\n board.pwm(2, 100) # Very dim\r\n else: # Day\r\n board.pwm(2, 0) # Off\r\n\r\nsmart_lighting()\r\n```\r\n\r\n---\r\n\r\n## Complete CLI Commands Reference\r\n\r\nESP-Linker provides 8 professional CLI commands for complete ESP8266 management:\r\n\r\n### 1. Device Detection\r\n```bash\r\n# Auto-detect ESP8266 boards\r\nesp-linker detect\r\n\r\n# Example output:\r\n# [+] ESP8266 Found: COM3\r\n# Description: Silicon Labs CP210x USB to UART Bridge\r\n# Manufacturer: Silicon Labs\r\n```\r\n\r\n### 2. Firmware Flashing\r\n```bash\r\n# Auto-flash with progress bars\r\nesp-linker flash\r\n\r\n# Specify port manually\r\nesp-linker flash --port COM3\r\n\r\n# Use different baud rate\r\nesp-linker flash --baud 115200\r\n\r\n# Show firmware information\r\nesp-linker flash --firmware-info\r\n```\r\n\r\n### 3. WiFi Configuration\r\n```bash\r\n# Interactive WiFi setup wizard\r\nesp-linker setup-wifi\r\n\r\n# Quick setup with credentials\r\nesp-linker setup-wifi --ssid \"MyWiFi\" --password \"MyPassword\"\r\n\r\n# Setup via serial port\r\nesp-linker setup-wifi --port COM3\r\n```\r\n\r\n### 4. Device Discovery\r\n```bash\r\n# Find all ESP-Linker devices on network\r\nesp-linker discover\r\n\r\n# Set custom timeout\r\nesp-linker discover --timeout 15\r\n\r\n# Example output:\r\n# [+] Found 2 ESP-Linker device(s):\r\n# 1. ESP-Linker v1.3.0 at 192.168.1.100\r\n# 2. ESP-Linker v1.3.0 at 192.168.1.101\r\n```\r\n\r\n### 5. Device Testing\r\n```bash\r\n# Comprehensive device testing\r\nesp-linker test 192.168.1.100\r\n\r\n# Test specific IP address\r\nesp-linker test --ip 192.168.1.100\r\n\r\n# The test includes:\r\n# - Device status verification\r\n# - GPIO pin testing\r\n# - PWM functionality\r\n# - Servo control\r\n# - Analog reading\r\n```\r\n\r\n### 6. Device Management\r\n```bash\r\n# List saved devices\r\nesp-linker devices list\r\n\r\n# Add a device\r\nesp-linker devices add --name \"Living Room\" --ip 192.168.1.100\r\n\r\n# Remove a device\r\nesp-linker devices remove \"Living Room\"\r\n\r\n# Show device details\r\nesp-linker devices info \"Living Room\"\r\n```\r\n\r\n### 7. Web Dashboard\r\n```bash\r\n# Launch web dashboard\r\nesp-linker dashboard\r\n\r\n# Custom port\r\nesp-linker dashboard --port 8080\r\n\r\n# Access at: http://localhost:5000\r\n```\r\n\r\n### 8. WiFi Management\r\n```bash\r\n# Enable AP mode (for configuration)\r\nesp-linker wifi enable-ap --ip 192.168.1.100\r\n\r\n# Disable AP mode\r\nesp-linker wifi disable-ap --ip 192.168.1.100\r\n\r\n# Check WiFi status\r\nesp-linker wifi status --ip 192.168.1.100\r\n```\r\n\r\n---\r\n\r\n## Python API Reference\r\n\r\n### Connection Methods\r\n\r\n#### Auto-Discovery (Recommended)\r\n```python\r\nfrom esp_linker import connect_auto\r\n\r\n# Automatically find and connect to ESP8266\r\nboard = connect_auto()\r\n\r\n# With timeout\r\nboard = connect_auto(timeout=15)\r\n```\r\n\r\n#### Manual IP Connection\r\n```python\r\nfrom esp_linker import ESPBoard\r\n\r\n# Connect to specific IP\r\nboard = ESPBoard(\"192.168.1.100\")\r\n\r\n# With custom timeout\r\nboard = ESPBoard(\"192.168.1.100\", timeout=10)\r\n```\r\n\r\n#### Context Manager (Recommended)\r\n```python\r\n# Automatically closes connection\r\nwith ESPBoard(\"192.168.1.100\") as board:\r\n board.write(2, 1)\r\n # Connection automatically closed\r\n```\r\n\r\n### GPIO Control Methods\r\n\r\n#### Digital I/O\r\n```python\r\n# Set pin mode (optional - auto-set by default)\r\nboard.set_mode(2, 'OUTPUT') # For digital output\r\nboard.set_mode(3, 'INPUT') # For digital input\r\n\r\n# Digital write (auto-sets OUTPUT mode)\r\nboard.write(2, 1) # HIGH\r\nboard.write(2, 0) # LOW\r\nboard.write(2, True) # HIGH (boolean)\r\nboard.write(2, False) # LOW (boolean)\r\n\r\n# Digital read\r\nvalue = board.read(3) # Returns 0 or 1\r\n```\r\n\r\n#### PWM Control\r\n```python\r\n# PWM output (auto-sets PWM mode)\r\nboard.pwm(4, 512) # 50% duty cycle (0-1023 range)\r\nboard.pwm(4, 0) # 0% (OFF)\r\nboard.pwm(4, 1023) # 100% (full ON)\r\n\r\n# Calculate percentage\r\npercentage = 75\r\npwm_value = int(percentage * 1023 / 100)\r\nboard.pwm(4, pwm_value)\r\n```\r\n\r\n#### Servo Control\r\n```python\r\n# Servo control (auto-sets SERVO mode)\r\nboard.servo(5, 90) # 90 degrees (0-180 range)\r\nboard.servo(5, 0) # Minimum angle\r\nboard.servo(5, 180) # Maximum angle\r\n```\r\n\r\n#### Analog Input\r\n```python\r\n# Read analog pin A0 (0-1024 range)\r\nvalue = board.read('A0')\r\n\r\n# Convert to voltage (ESP8266 = 3.3V max)\r\nvoltage = value * 3.3 / 1024\r\n\r\n# Convert to percentage\r\npercentage = value * 100 / 1024\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udd27 Troubleshooting Guide\r\n\r\n### \u274c Common Issues and Solutions\r\n\r\n#### 1. \"No ESP8266 boards detected\"\r\n```bash\r\n# Problem: esp-linker detect shows no devices\r\n# Solutions:\r\n1. Check USB cable connection\r\n2. Install USB drivers (CP210x or CH340)\r\n3. Try different USB port\r\n4. Specify port manually: esp-linker flash --port COM3\r\n```\r\n\r\n#### 2. \"Failed to connect to ESP8266\"\r\n```bash\r\n# Problem: Can't connect to device IP\r\n# Solutions:\r\n1. Check WiFi connection: esp-linker wifi status --ip YOUR_IP\r\n2. Verify device is on same network\r\n3. Try auto-discovery: esp-linker discover\r\n4. Check firewall settings\r\n5. Restart ESP8266: esp-linker restart --ip YOUR_IP\r\n```\r\n\r\n#### 3. \"Pin not set to OUTPUT mode\" (v1.2.1 and earlier)\r\n```python\r\n# Problem: GPIO error when using write()\r\n# Solution: Update to v1.3.0 or set pin mode manually\r\nboard.set_mode(2, 'OUTPUT') # Set pin mode first\r\nboard.write(2, 1) # Then write value\r\n\r\n# Or update ESP-Linker:\r\n# pip install --upgrade esp-linker\r\n```\r\n\r\n#### 4. \"Device not found during discovery\"\r\n```bash\r\n# Problem: esp-linker discover finds no devices\r\n# Solutions:\r\n1. Ensure ESP8266 is connected to WiFi\r\n2. Check if on same network subnet\r\n3. Disable VPN if active\r\n4. Try manual IP: esp-linker test --ip 192.168.1.100\r\n5. Check router's connected devices list\r\n```\r\n\r\n#### 5. \"Firmware flashing failed\"\r\n```bash\r\n# Problem: Flashing fails or times out\r\n# Solutions:\r\n1. Hold BOOT button during flashing (some boards)\r\n2. Try lower baud rate: esp-linker flash --baud 115200\r\n3. Use different USB cable\r\n4. Close other serial programs (Arduino IDE, etc.)\r\n5. Try different USB port\r\n```\r\n\r\n### \ud83d\udd0d Diagnostic Commands\r\n\r\n```bash\r\n# Check ESP-Linker installation\r\nesp-linker --version\r\npython -c \"import esp_linker; print('\u2705 ESP-Linker installed')\"\r\n\r\n# Test device connection\r\nesp-linker test 192.168.1.100\r\n\r\n# Check device status\r\nesp-linker wifi status --ip 192.168.1.100\r\n\r\n# Scan for devices\r\nesp-linker discover --timeout 30\r\n\r\n# Check serial ports\r\nesp-linker detect\r\n```\r\n\r\n### \ud83d\udcca Performance Tips\r\n\r\n#### For ESP8266 Optimization:\r\n- **Use auto-mode**: Let ESP-Linker set pin modes automatically\r\n- **Batch operations**: Use `board.batch()` for multiple GPIO operations\r\n- **Connection pooling**: Reuse board connections instead of creating new ones\r\n- **Timeout settings**: Adjust timeouts for slow networks\r\n\r\n```python\r\n# Optimized code example\r\nwith ESPBoard(\"192.168.1.100\", timeout=15) as board:\r\n # Batch multiple operations\r\n operations = [\r\n {'type': 'write', 'pin': 2, 'value': 1},\r\n {'type': 'pwm', 'pin': 4, 'value': 512},\r\n {'type': 'servo', 'pin': 5, 'angle': 90}\r\n ]\r\n board.batch(operations)\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udcda API Reference Summary\r\n\r\n### \ud83d\udd0c Connection Classes\r\n```python\r\n# Auto-discovery connection\r\nboard = connect_auto(timeout=10)\r\n\r\n# Manual IP connection\r\nboard = ESPBoard(\"192.168.1.100\", timeout=10)\r\n\r\n# Context manager (auto-close)\r\nwith ESPBoard(\"192.168.1.100\") as board:\r\n # Your code here\r\n```\r\n\r\n### \ud83c\udf9b\ufe0f GPIO Control Methods\r\n```python\r\n# Digital I/O\r\nboard.write(pin, value, auto_mode=True) # Digital write\r\nboard.read(pin) # Digital/analog read\r\nboard.set_mode(pin, mode) # Set pin mode manually\r\n\r\n# PWM Control\r\nboard.pwm(pin, value, auto_mode=True) # PWM output (0-1023)\r\n\r\n# Servo Control\r\nboard.servo(pin, angle, auto_mode=True) # Servo angle (0-180)\r\n\r\n# Device Information\r\nboard.status() # Device status\r\nboard.capabilities() # Pin capabilities\r\nboard.ping() # Test connection\r\nboard.close() # Close connection\r\n```\r\n\r\n### \ud83d\udce1 Supported Pin Modes\r\n- **INPUT**: Digital input reading\r\n- **OUTPUT**: Digital output writing\r\n- **PWM**: Pulse Width Modulation output\r\n- **SERVO**: Servo motor control\r\n\r\n### \ud83d\udccd ESP8266 Pin Reference\r\n```\r\nGPIO Pin | NodeMCU Pin | Function\r\n---------|-------------|----------\r\nGPIO0 | D3 | Digital I/O\r\nGPIO2 | D4 | Digital I/O, Built-in LED\r\nGPIO4 | D2 | Digital I/O, PWM\r\nGPIO5 | D1 | Digital I/O, PWM\r\nGPIO12 | D6 | Digital I/O, PWM\r\nGPIO13 | D7 | Digital I/O, PWM\r\nGPIO14 | D5 | Digital I/O, PWM\r\nGPIO15 | D8 | Digital I/O, PWM\r\nGPIO16 | D0 | Digital I/O (no PWM)\r\nA0 | A0 | Analog Input (0-1024)\r\n```\r\n\r\n---\r\n\r\n## \ud83c\udd98 Support and Community\r\n\r\n### \ud83d\udcde Get Help\r\n- **\ud83d\udce7 Email**: [skrelectronicslab@gmail.com](mailto:skrelectronicslab@gmail.com)\r\n- **\ud83c\udf10 Website**: [www.skrelectronicslab.com](https://www.skrelectronicslab.com)\r\n- **\ud83d\udcfa YouTube**: [SKR Electronics Lab](https://www.youtube.com/@skr_electronics_lab)\r\n- **\ud83d\udcf1 Instagram**: [@skr_electronics_lab](https://www.instagram.com/skr_electronics_lab)\r\n- **\u2615 Support**: [Buy me a coffee](https://buymeacoffee.com/skrelectronics)\r\n\r\n### \ud83d\udc1b Report Issues\r\nFound a bug? Have a feature request? Please report it!\r\n\r\n### \ud83e\udd1d Contributing\r\nESP-Linker is open source! Contributions are welcome.\r\n\r\n### \ud83d\udcc4 License\r\nESP-Linker is released under the MIT License.\r\n\r\n---\r\n\r\n## \ud83c\udf89 What's New in v1.3.0\r\n\r\n### \u2728 New Features\r\n- **\ud83e\udd16 Auto-Mode Setting**: Pins automatically configured - no manual setup needed\r\n- **\ud83d\udd04 Smart AP Management**: AP mode auto-disables when WiFi connects\r\n- **\u26a1 Ultra-Lightweight Web UI**: Optimized for ESP8266 performance\r\n- **\ud83d\udcca Enhanced Dashboard**: Modern, responsive web interface\r\n- **\ud83d\udee1\ufe0f Better Error Handling**: Improved error messages and recovery\r\n\r\n### \ud83d\udd27 Improvements\r\n- **\ud83d\udcf1 Mobile-Friendly**: Web interfaces work perfectly on phones\r\n- **\ud83d\ude80 Performance**: Faster GPIO operations and reduced memory usage\r\n- **\ud83c\udfaf User Experience**: More intuitive CLI commands and better documentation\r\n- **\ud83d\udd12 Stability**: Enhanced connection reliability and error recovery\r\n\r\n### \ud83c\udd95 New CLI Commands\r\n```bash\r\nesp-linker wifi enable-ap # Enable AP mode manually\r\nesp-linker wifi disable-ap # Disable AP mode\r\nesp-linker wifi status # Check WiFi status\r\n```\r\n\r\n---\r\n\r\n**\ud83d\ude80 Ready to start your IoT journey? Install ESP-Linker now and transform your ESP8266 into a powerful wireless device!**\r\n\r\n```bash\r\npip install esp-linker\r\n```\r\n\r\n*Made with \u2764\ufe0f by [SK Raihan](https://www.skrelectronicslab.com) / SKR Electronics Lab*\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Professional wireless GPIO control for ESP8266 boards with PyFirmata-inspired interface, complete IoT solution with firmware, CLI tools, and web dashboard",
"version": "1.3.5",
"project_urls": {
"Bug Tracker": "https://github.com/skr-electronics-lab/esp-linker/issues",
"Documentation": "https://www.skrelectronicslab.com/esp-linker",
"Download": "https://pypi.org/project/esp-linker/",
"Homepage": "https://www.skrelectronicslab.com",
"Instagram": "https://www.instagram.com/skr_electronics_lab",
"PyPI": "https://pypi.org/project/esp-linker/",
"Source Code": "https://github.com/skr-electronics-lab/esp-linker",
"Support": "https://buymeacoffee.com/skrelectronics",
"YouTube Channel": "https://www.youtube.com/@skr_electronics_lab"
},
"split_keywords": [
"esp8266",
" gpio",
" iot",
" wireless",
" arduino",
" microcontroller",
" automation",
" robotics",
" electronics",
" maker",
" diy",
" wifi",
" remote-control",
" pyfirmata",
" esp-linker",
" nodemcu",
" wemos",
" embedded",
" hardware",
" sensor",
" actuator",
" smart-home",
" internet-of-things",
" esp32",
" micropython",
" circuitpython",
" raspberry-pi",
" home-automation",
" industrial-iot",
" edge-computing",
" wireless-communication",
" web-dashboard",
" cli-tools",
" firmware",
" skr-electronics-lab",
" professional",
" production-ready",
" cross-platform"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e2727d2e90b96bde33951f547ee74485dd9d12161731b7688382919abebb48f7",
"md5": "408b393ef98db4181c08e265d29dc1d7",
"sha256": "92b4a4a34df277c046dbeeaff91da2de7b51f095359e334957e90a88f525b957"
},
"downloads": -1,
"filename": "esp_linker-1.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "408b393ef98db4181c08e265d29dc1d7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 318835,
"upload_time": "2025-07-14T19:50:17",
"upload_time_iso_8601": "2025-07-14T19:50:17.652436Z",
"url": "https://files.pythonhosted.org/packages/e2/72/7d2e90b96bde33951f547ee74485dd9d12161731b7688382919abebb48f7/esp_linker-1.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "be370c3446b9313330f5ea81b3f7d1f1c0d49efc3fb8f093a5a6d5746ffe2509",
"md5": "de95440a73cd2a4698dfae0c87227214",
"sha256": "4ebbc3d1a753a1b1ed436def043f5c960385847c94f3f8e09eb6e56a04467e4c"
},
"downloads": -1,
"filename": "esp_linker-1.3.5.tar.gz",
"has_sig": false,
"md5_digest": "de95440a73cd2a4698dfae0c87227214",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 329188,
"upload_time": "2025-07-14T19:50:19",
"upload_time_iso_8601": "2025-07-14T19:50:19.621509Z",
"url": "https://files.pythonhosted.org/packages/be/37/0c3446b9313330f5ea81b3f7d1f1c0d49efc3fb8f093a5a6d5746ffe2509/esp_linker-1.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 19:50:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "skr-electronics-lab",
"github_project": "esp-linker",
"github_not_found": true,
"lcname": "esp-linker"
}
JSON
