ESP8266-Station/xpressnet.md

XpressNet Command Reference

This document describes the available XpressNet commands and how to implement them in your command station firmware.

XpressNet Command Table

Command Name	Code (Hex)	Description	Typical Usage
Locomotive Speed	0xE4	Set speed and direction for a locomotive	Control train movement
Function Group 1	0xE4	Control F0-F4 functions	Lights, sound, etc.
Function Group 2	0xE4	Control F5-F8 functions	Extended functions
Accessory Control	0x90	Switch turnouts, signals, etc.	Control layout accessories
Read Feedback	0xF2	Query feedback modules	Detect occupancy, sensors
Programming on Main	0xEF	Write CVs to decoders on main track	Decoder configuration
Programming Track	0xED	Write/read CVs on programming track	Safe decoder programming
Request Version	0x21	Request command station version	Handshake, diagnostics
Emergency Stop	0x80	Stop all locomotives immediately	Safety/emergency

Note: Actual codes and command structure may vary by implementation. Refer to the official XpressNet protocol documentation for full details.

Implementing XpressNet in Your Command Station

1. Serial Communication: XpressNet typically uses RS485 or TTL UART. Set up a serial interface at the required baud rate (commonly 62500 baud).

2. Command Parsing: In your firmware, implement a parser that reads incoming bytes and matches them to the command table above. Use a state machine to handle multi-byte commands.

3. Command Handling:

   • For each recognized command, implement a handler function (e.g., handleLocomotiveSpeed(), handleAccessoryControl()).
   • Extract parameters (address, speed, function bits, etc.) from the command bytes.
   • Update your internal state or send DCC packets as needed.

4. Response Generation: Some commands require a response (e.g., version request, feedback read). Format and send the appropriate reply bytes.

5. Error Handling: Implement checks for invalid or unsupported commands and respond with error codes if required by the protocol.

6. Integration with DCC: For commands that affect trains or accessories, translate XpressNet commands into DCC packets and send them to the track using your DCC output routines.

Example: Handling a Locomotive Speed Command

void handleLocomotiveSpeed(const uint8_t* data, size_t len) {
    // Parse address, speed, direction from data
    // Update DCC packet buffer
    // Send DCC packet to track
}

References

• XpressNet Protocol Specification
• DCC Protocol Overview

---

Custom (DIY) XpressNet Extensions

You can add your own special commands to XpressNet by using unused command codes. Below are examples for switching mode and power control.

Command Name	Code (Hex)	Payload Example	Description
Switch Mode	0xF0	0x00	Switch to Analog mode
		0x01	Switch to DCC mode
		0x02	Switch to Marklin mode
Power Track	0xF1	0x00	Power OFF
		0x01	Power ON

Example Implementation in Firmware

// Handle custom XpressNet commands
void handleCustomXpressNet(const uint8_t* data, size_t len) {
    uint8_t cmd = data[0];
    switch (cmd) {
        case 0xF0: // Switch Mode
            if (len > 1) {
                uint8_t mode = data[1];
                switch (mode) {
                    case 0x00: /* setAnalogMode(); */ break;
                    case 0x01: /* setDCCMode(); */ break;
                    case 0x02: /* setMarklinMode(); */ break;
                }
            }
            break;
        case 0xF1: // Power Track
            if (len > 1) {
                if (data[1] == 0x01) {
                    // powerOnTrack();
                } else {
                    // powerOffTrack();
                }
            }
            break;
        // ... handle other custom commands ...
    }
}

---

XpressNet over IP (WebSocket)

You can encapsulate XpressNet packets in WebSocket frames for remote control over IP. On the ESP8266, use a WebSocket server library (e.g., arduinoWebSockets).

Basic Steps:

1. Start a WebSocket server on the ESP8266.
2. On message received, treat the payload as an XpressNet packet and process it.
3. Send any response packets back over WebSocket.

Example (pseudo-code):

#include <WebSocketsServer.h>
WebSocketsServer webSocket = WebSocketsServer(81);

void onWebSocketEvent(uint8_t num, WStype_t type, uint8_t * payload, size_t length) {
    if (type == WStype_BIN) {
        // Process XpressNet packet
        handleXpressNet(payload, length);
        // Optionally send response:
        // webSocket.sendBIN(num, response, responseLen);
    }
}

void setup() {
    // ... WiFi setup ...
    webSocket.begin();
    webSocket.onEvent(onWebSocketEvent);
}

void loop() {
    webSocket.loop();
}

---

These extensions allow you to add custom features and remote control to your XpressNet command station.