WebREPL Protocol Specifications

This repository contains protocol specifications for WebREPL, a WebSocket-based protocol for accessing remote Python REPL (Read-Eval-Print Loop) and performing file transfer operations, primarily used with MicroPython devices.

An RFC-style format specification of the original WebREPL protocol that describes:

• Connection & Authentication: Password-based authentication over WebSocket
• Terminal Mode: Interactive REPL access using WebSocket Text frames
• File Transfer Mode: Binary frame-based file operations with "WA"/"WB" magic bytes
• Operations:
  • PUT_FILE - Upload files to device
  • GET_FILE - Download files from device
  • GET_VER - Get protocol version

Key Characteristics:

• Uses WebSocket Text frames for REPL I/O
• Uses WebSocket Binary frames with 82-byte fixed headers for file transfers
• 64-character filename limit
• Magic bytes: "WA" (client→server), "WB" (server→client)

A modern, next-generation WebREPL protocol using CBOR encoding and channel multiplexing.

Subprotocol Identifier: webrepl.binary.v1

Major Improvements:

• Channelized Communication: 255 independent channels for multiplexing
• CBOR Encoding: Compact, self-describing binary messages
• Binary Bytecode Support: Native .mpy execution
• TFTP-based File Transfers: Reliable, resumable block-based transfers
• Event System: Structured logs and system notifications
• Extensible: Optional trailing fields for future features

Channel Allocation:

• Channel 0: Events (auth, logs, notifications)
• Channel 1: Terminal REPL (Human-Machine Interface)
• Channel 2: Machine-to-Machine RPC
• Channel 3: Debug output
• Channel 23: File operations (TFTP-based)
• Channels 4-22: Reserved for future use
• Channels 24-254: Application-defined

Features:

• Sub-10 byte message overhead for common operations
• Unlimited filename lengths
• File metadata (timestamps, permissions)
• Progress tracking for file transfers
• 4KB block sizes aligned with ESP32 flash sectors
• Support for files up to 268 MB

Build browser-based development environments for MicroPython devices with:

• Multiple simultaneous terminal sessions
• Background file operations
• Real-time event notifications
• Structured logging

• Automated device configuration
• Remote monitoring and control
• Firmware updates
• Data collection from IoT devices

• Interactive debugging
• Binary bytecode deployment
• Filesystem management
• Over-the-air updates

• ✅ Server: Implemented in MicroPython (ESP32, ESP8266)
• ✅ Client: Multiple implementations (webrepl_cli.py, web clients)
• ✅ Production: Widely deployed

• 🚧 Server: Under development (MicroPython/ESP32)
• 🚧 Client: Reference implementation in progress
• 📋 Status: Draft specification

# On MicroPython device
import webrepl
webrepl.start(password='mypassword')

# Command-line client
webrepl_cli.py -p mypassword ws://192.168.4.1:8266/

See the detailed examples in webrepl_binary_protocol_rfc.md:

• Server implementation (MicroPython)
• Client implementation (JavaScript)
• Message format examples
• Protocol flows

⚠️ Important Security Notes:

1. Use WSS (WebSocket Secure) in production deployments

2. WS (unencrypted) should only be used for:

   • Local development
   • Isolated/private networks
   • Initial device configuration on AP mode

3. Authentication: Both protocols use password-based authentication

4. Rate Limiting: Implement protection against brute-force attacks

5. Input Validation: Always validate paths, sizes, and opcodes

This repository contains protocol specifications. Implementations should be contributed to:

• MicroPython: For server-side implementation
• ScriptO Studio: For web-based client implementation
• Other projects: As appropriate

• MicroPython - Python for microcontrollers
• ScriptO Studio - Web-based MicroPython IDE
• mpDirect - Direct MicroPython communication layer

Jonathan Peace
Scripto Studio
Email: jep@scripto.studio.com

These specifications are provided for informational purposes to enable interoperable implementations.

Status:

• webrepl_rfc.txt: Informational (describes existing protocol)
• webrepl_binary_protocol_rfc.md: Draft (v1.0, December 2025)