Xteink-X4-crosspoint-reader/docs/webserver-endpoints.md

Webserver Endpoints

This document describes all HTTP and WebSocket endpoints available on the CrossPoint Reader webserver.

• Webserver Endpoints
  • Overview
  • HTTP Endpoints
    • GET / - Home Page
    • GET /files - File Browser Page
    • GET /apps - Apps (Developer) Page
    • GET /api/status - Device Status
    • GET /api/files - List Files
    • POST /upload - Upload File
    • POST /upload-app - Upload App (Developer)
    • POST /mkdir - Create Folder
    • POST /delete - Delete File or Folder
  • WebSocket Endpoint
    • Port 81 - Fast Binary Upload
  • Network Modes
    • Station Mode (STA)
    • Access Point Mode (AP)
  • Notes

Overview

The CrossPoint Reader exposes a webserver for file management and device monitoring:

• HTTP Server: Port 80
• WebSocket Server: Port 81 (for fast binary uploads)

---

HTTP Endpoints

GET / - Home Page

Serves the home page HTML interface.

Request:

curl http://crosspoint.local/

Response: HTML page (200 OK)

---

GET /files - File Browser Page

Serves the file browser HTML interface.

Request:

curl http://crosspoint.local/files

Response: HTML page (200 OK)

---

GET /apps - Apps (Developer) Page

Serves the Apps (Developer) HTML interface.

This is a developer-oriented page for uploading app binaries to the SD card under /.crosspoint/apps/. Installing/running apps still happens on the device: Home → Apps.

Request:

curl http://crosspoint.local/apps

Response: HTML page (200 OK)

---

GET /api/status - Device Status

Returns JSON with device status information.

Request:

curl http://crosspoint.local/api/status

Response (200 OK):

{
  "version": "1.0.0",
  "ip": "192.168.1.100",
  "mode": "STA",
  "rssi": -45,
  "freeHeap": 123456,
  "uptime": 3600
}

Field	Type	Description
version	string	CrossPoint firmware version
ip	string	Device IP address
mode	string	"STA" (connected to WiFi) or "AP" (access point mode)
rssi	number	WiFi signal strength in dBm (0 in AP mode)
freeHeap	number	Free heap memory in bytes
uptime	number	Seconds since device boot

---

GET /api/files - List Files

Returns a JSON array of files and folders in the specified directory.

Request:

# List root directory
curl http://crosspoint.local/api/files

# List specific directory
curl "http://crosspoint.local/api/files?path=/Books"

Query Parameters:

Parameter	Required	Default	Description
path	No	/	Directory path to list

Response (200 OK):

[
  {"name": "MyBook.epub", "size": 1234567, "isDirectory": false, "isEpub": true},
  {"name": "Notes", "size": 0, "isDirectory": true, "isEpub": false},
  {"name": "document.pdf", "size": 54321, "isDirectory": false, "isEpub": false}
]

Field	Type	Description
name	string	File or folder name
size	number	Size in bytes (0 for directories)
isDirectory	boolean	true if the item is a folder
isEpub	boolean	true if the file has .epub extension

Notes:

• Hidden files (starting with .) are automatically filtered out
• System folders (System Volume Information, XTCache) are hidden

---

POST /upload - Upload File

Uploads a file to the SD card via multipart form data.

Request:

# Upload to root directory
curl -X POST -F "file=@mybook.epub" http://crosspoint.local/upload

# Upload to specific directory
curl -X POST -F "file=@mybook.epub" "http://crosspoint.local/upload?path=/Books"

Query Parameters:

Parameter	Required	Default	Description
path	No	/	Target directory for the upload

Response (200 OK):

File uploaded successfully: mybook.epub

Error Responses:

Status	Body	Cause
400	Failed to create file on SD card	Cannot create file
400	Failed to write to SD card - disk may be full	Write error during upload
400	Failed to write final data to SD card	Error flushing final buffer
400	Upload aborted	Client aborted the upload
400	Unknown error during upload	Unspecified error

Notes:

• Existing files with the same name will be overwritten
• Uses a 4KB buffer for efficient SD card writes

---

POST /upload-app - Upload App (Developer)

Uploads an app binary to the SD card under /.crosspoint/apps/<appId>/ and creates/updates app.json.

Important: this endpoint does not install the app. Install on device via Home → Apps.

Request:

curl -X POST \
  -F "file=@app.bin" \
  "http://crosspoint.local/upload-app?appId=chess-puzzles&name=Chess%20Puzzles&version=0.1.0"

Query Parameters:

Parameter	Required	Description
appId	Yes	App identifier; allowed chars: [A-Za-z0-9._-], max 64, no slashes
name	Yes	Display name
version	Yes	Version string
author	No	Author string
description	No	Short description
minFirmware	No	Minimum CrossPoint firmware version required

Response (200 OK):

App uploaded. Install on device: Home -> Apps -> <Name> v<Version>

Error Responses:

Status	Body	Cause
400	Missing required fields: appId, name, version	Missing query parameters
400	Invalid appId	appId failed validation
500	SD card not ready	SD not mounted/ready
500	Failed to create app.bin.tmp	File create failed (disk full / FS error)
500	Invalid firmware image (bad magic byte)	Uploaded file is not an ESP32 image

Notes:

• Upload uses a temp file (app.bin.tmp) and finalizes to app.bin on success.
• Partial uploads are cleaned up on abort/failure.

---

POST /mkdir - Create Folder

Creates a new folder on the SD card.

Request:

curl -X POST -d "name=NewFolder&path=/" http://crosspoint.local/mkdir

Form Parameters:

Parameter	Required	Default	Description
name	Yes	-	Name of the folder to create
path	No	/	Parent directory path

Response (200 OK):

Folder created: NewFolder

Error Responses:

Status	Body	Cause
400	Missing folder name	name parameter not provided
400	Folder name cannot be empty	Empty folder name
400	Folder already exists	Folder with same name exists
500	Failed to create folder	SD card error

---

POST /delete - Delete File or Folder

Deletes a file or folder from the SD card.

Request:

# Delete a file
curl -X POST -d "path=/Books/mybook.epub&type=file" http://crosspoint.local/delete

# Delete an empty folder
curl -X POST -d "path=/OldFolder&type=folder" http://crosspoint.local/delete

Form Parameters:

Parameter	Required	Default	Description
path	Yes	-	Path to the item to delete
type	No	file	Type of item: file or folder

Response (200 OK):

Deleted successfully

Error Responses:

Status	Body	Cause
400	Missing path	path parameter not provided
400	Cannot delete root directory	Attempted to delete /
400	Folder is not empty. Delete contents first.	Non-empty folder
403	Cannot delete system files	Hidden file (starts with .)
403	Cannot delete protected items	Protected system folder
404	Item not found	Path does not exist
500	Failed to delete item	SD card error

Protected Items:

• Files/folders starting with .
• System Volume Information
• XTCache

---

WebSocket Endpoint

Port 81 - Fast Binary Upload

A WebSocket endpoint for high-speed binary file uploads. More efficient than HTTP multipart for large files.

Connection:

ws://crosspoint.local:81/

Protocol:

1. Client sends TEXT message: START:<filename>:<size>:<path>
2. Server responds with TEXT: READY
3. Client sends BINARY messages with file data chunks
4. Server sends TEXT progress updates: PROGRESS:<received>:<total>
5. Server sends TEXT when complete: DONE or ERROR:<message>

Example Session:

Client -> "START:mybook.epub:1234567:/Books"
Server -> "READY"
Client -> [binary chunk 1]
Client -> [binary chunk 2]
Server -> "PROGRESS:65536:1234567"
Client -> [binary chunk 3]
...
Server -> "PROGRESS:1234567:1234567"
Server -> "DONE"

Error Messages:

Message	Cause
ERROR:Failed to create file	Cannot create file on SD card
ERROR:Invalid START format	Malformed START message
ERROR:No upload in progress	Binary data received without START
ERROR:Write failed - disk full?	SD card write error

Example with websocat:

# Interactive session
websocat ws://crosspoint.local:81

# Then type:
START:mybook.epub:1234567:/Books
# Wait for READY, then send binary data

Notes:

• Progress updates are sent every 64KB or at completion
• Disconnection during upload will delete the incomplete file
• Existing files with the same name will be overwritten

---

Network Modes

The device can operate in two network modes:

Station Mode (STA)

• Device connects to an existing WiFi network
• IP address assigned by router/DHCP
• mode field in /api/status returns "STA"
• rssi field shows signal strength

Access Point Mode (AP)

• Device creates its own WiFi hotspot
• Default IP is typically 192.168.4.1
• mode field in /api/status returns "AP"
• rssi field returns 0

---

Notes

• These examples use crosspoint.local. If your network does not support mDNS or the address does not resolve, replace it with the specific IP Address displayed on your device screen (e.g., http://192.168.1.102/).
• All paths on the SD card start with /
• Trailing slashes are automatically stripped (except for root /)
• The webserver uses chunked transfer encoding for file listings