Skip to content

webserver-endpoints.md

Latest commit

 

History

History
332 lines (245 loc) · 10.1 KB

webserver-endpoints.md

File metadata and controls

332 lines (245 loc) · 10.1 KB

Webserver Endpoints

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

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 /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 /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 one or more files or empty folders from the SD card.

Request:

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

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

# Delete multiple items
curl -X POST -d 'paths=["/Books/old.epub","/OldFolder"]' http://crosspoint.local/delete

Form Parameters:

Parameter Required Default Description
path Yes, unless paths is provided - Path to one item to delete
paths Yes, unless path is provided - JSON array of paths to delete

Response (200 OK):

All items deleted successfully

Error Responses:

Status Body Cause
400 Missing "path" or "paths" argument Neither parameter was provided
400 Provide either 'path' or 'paths', not both Both delete parameters were sent
400 Invalid paths format paths was not valid JSON
400 No paths provided paths was an empty JSON array
500 Failed to delete some items: ... One or more paths could not be deleted

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