Skip to content

webserver-endpoints.md

Latest commit

 

History

History
502 lines (360 loc) · 11 KB

webserver-endpoints.md

File metadata and controls

502 lines (360 loc) · 11 KB
Raw

Webserver Endpoints

This document describes the HTTP, WebSocket, WebDAV, and discovery endpoints available while CrossInk is in File Transfer or Calibre Wireless mode.

  • HTTP server: port 80
  • WebSocket upload server: port 81
  • UDP discovery listener: port 8134
  • WebDAV: port 80, handled by the same HTTP server

Examples use crosspoint.local. If mDNS does not resolve on your network, use the IP address shown on the device screen.

HTTP Pages

Method Path Purpose
GET / Home/status page
GET /files File manager page
GET /settings Web settings page
GET /fonts SD-card font manager page
GET /js/jszip.min.js JavaScript asset used by the file manager

Device Status

GET /api/status

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

Response:

{
  "version": "1.0.0",
  "ip": "192.168.1.100",
  "mode": "STA",
  "rssi": -45,
  "freeHeap": 123456,
  "uptime": 3600,
  "device": "X4"
}
Field Type Description
version string Firmware version
ip string Device IP address
mode string "STA" for joined Wi-Fi or "AP" for hotspot mode
rssi number Wi-Fi RSSI in dBm; 0 in AP mode
freeHeap number Free heap in bytes
uptime number Seconds since boot
device string "X3" or "X4" hardware detection

File Management

GET /api/files

Lists files and folders under a directory.

curl "http://crosspoint.local/api/files?path=/Books"

Query parameters:

Parameter Required Default Description
path No / Directory to list

Response:

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

Hidden dotfiles are omitted unless the device setting showHiddenFiles is enabled. System Volume Information and XTCache are always hidden/protected.

GET /download

Downloads a file from the SD card.

curl -OJ "http://crosspoint.local/download?path=/Books/MyBook.epub"

Query parameters:

Parameter Required Description
path Yes File path to download

Protected dotfiles, System Volume Information, and XTCache cannot be downloaded. EPUB files are served as application/epub+zip; other files use application/octet-stream.

POST /upload

Uploads a file with HTTP multipart form data.

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

Query parameters:

Parameter Required Default Description
path No / Destination directory

Successful response:

File uploaded successfully: mybook.epub

Notes:

  • Existing files with the same name are overwritten.
  • EPUB cache data for the uploaded path is cleared after a successful upload.
  • HTTP upload uses a 4 KB write buffer before flushing to the SD card.

POST /mkdir

Creates a folder.

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

Form parameters:

Parameter Required Default Description
name Yes - New folder name
path No / Parent folder

POST /rename

Renames a file.

curl -X POST -d "path=/Books/old.epub&name=new.epub" http://crosspoint.local/rename

Form parameters:

Parameter Required Description
path Yes Existing file path
name Yes New file name, not a path

Only files can be renamed through this endpoint. The old EPUB cache path is cleared before the rename.

POST /move

Moves a file into an existing folder.

curl -X POST -d "path=/Books/mybook.epub&dest=/Read" http://crosspoint.local/move

Form parameters:

Parameter Required Description
path Yes Existing file path
dest Yes Existing destination folder

Only files can be moved through this endpoint. The old EPUB cache path is cleared before the move.

POST /delete

Deletes one or more files or empty folders.

curl -X POST -d "path=/Books/mybook.epub" http://crosspoint.local/delete
curl -X POST -d 'paths=["/Books/old.epub","/OldFolder"]' http://crosspoint.local/delete

Form parameters:

Parameter Required Description
path Yes, unless paths is provided Single path to delete
paths Yes, unless path is provided JSON array of paths to delete

Protected items cannot be deleted. Non-empty folders are rejected. EPUB cache data for deleted files is cleared.

Settings API

GET /api/settings

Returns a streamed JSON array of editable settings. Each item contains common fields plus type-specific fields.

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

Example item:

{
  "key": "fontSize",
  "name": "Font Size",
  "category": "Reader",
  "type": "enum",
  "value": 1,
  "options": ["10 pt", "12 pt", "14 pt", "16 pt"]
}

Types:

Type Extra fields
toggle value (0 or 1)
enum value, options
value value, min, max, step
string value

The font-family setting includes SD-card font families when they are installed. For enum settings, value is the selected option's display index in the returned options array. It is not necessarily the raw firmware enum value.

POST /api/settings

Applies a partial settings update from a JSON object.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"fontSize":2,"showHiddenFiles":1}' \
  http://crosspoint.local/api/settings

Successful response:

Applied 2 setting(s)

Font Management API

GET /api/fonts

Lists installed SD-card font families.

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

Response:

{
  "maxFamilies": 128,
  "families": [
    {
      "name": "Literata",
      "sizes": [12, 14, 16, 18],
      "files": [
        {"name": "Literata_12.cpfont", "size": 123456}
      ]
    }
  ]
}

POST /api/fonts/upload

Uploads one .cpfont file into a family folder.

curl -X POST \
  -F "family=Literata" \
  -F "file=@Literata_12.cpfont" \
  http://crosspoint.local/api/fonts/upload

The handler validates the family name, .cpfont filename, and CPFONT magic bytes before accepting the file.

Successful response:

{"ok":true}

POST /api/fonts/delete

Deletes an installed font family.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"family":"Literata"}' \
  http://crosspoint.local/api/fonts/delete

Successful response:

{"ok":true}

OPDS Server API

GET /api/opds

Lists saved OPDS servers. Passwords are never returned.

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

Response:

[
  {
    "index": 0,
    "name": "My Catalog",
    "url": "http://calibre.local:8080/opds",
    "username": "reader",
    "hasPassword": true
  }
]

POST /api/opds

Adds or updates an OPDS server. Include index to update an existing entry. If password is omitted during an update, the existing password is preserved.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"My Catalog","url":"http://calibre.local:8080/opds","username":"reader","password":"secret"}' \
  http://crosspoint.local/api/opds

POST /api/opds/delete

Deletes an OPDS server by index.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"index":0}' \
  http://crosspoint.local/api/opds/delete

Wi-Fi Credential API

GET /api/wifi

Lists saved Wi-Fi networks. Passwords are never returned.

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

Response:

[
  {
    "index": 0,
    "ssid": "HomeWiFi",
    "hasPassword": true,
    "isLastConnected": true
  }
]

POST /api/wifi

Adds or updates a saved Wi-Fi network. Include index to update an existing entry. If password is omitted during an update, the existing password is preserved.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"ssid":"HomeWiFi","password":"secret"}' \
  http://crosspoint.local/api/wifi

POST /api/wifi/delete

Deletes a saved Wi-Fi network by index.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"index":0}' \
  http://crosspoint.local/api/wifi/delete

WebSocket Upload

Port 81

The WebSocket path is used for fast binary uploads from the file manager and Calibre plugin workflows.

Connection:

ws://crosspoint.local:81/

Protocol:

  1. Client sends text: START:<filename>:<size>:<path>
  2. Server replies READY
  3. Client sends binary chunks
  4. Server sends PROGRESS:<received>:<total> every 64 KB or at completion
  5. Server sends DONE when complete or ERROR:<message> on failure

Example session:

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

Error messages include:

Message Cause
ERROR:Upload already in progress A second upload was started before the first completed
ERROR:Invalid START format Malformed START message or invalid size token
ERROR:Failed to create file Destination file could not be opened
ERROR:No upload in progress Binary data arrived without a matching START
ERROR:Upload overflow Client sent more bytes than declared
ERROR:Write failed - disk full? SD write failed

Incomplete WebSocket uploads are deleted on disconnect or error.

WebDAV

The same HTTP server registers a WebDAV-compatible handler for file manager clients.

Supported methods:

OPTIONS, GET, HEAD, PUT, DELETE, PROPFIND, MKCOL, MOVE, COPY, LOCK, UNLOCK

Notes:

  • PUT writes to a temporary .davtmp file first, then renames it into place.
  • Protected paths are rejected.
  • LOCK and UNLOCK are accepted for client compatibility only. The server does not implement full WebDAV Class 2 locking semantics such as persistent locks or lock discovery.

UDP Discovery

The server listens on UDP port 8134. When it receives the text payload hello, it replies to the sender with:

crosspoint (on <hostname>);81

The final field is the WebSocket upload port.

Network Modes

Station Mode (STA)

  • Device joins an existing 2.4 GHz Wi-Fi network.
  • crosspoint.local is advertised with mDNS when available.
  • /api/status returns "mode": "STA" and RSSI in dBm.

Access Point Mode (AP)

  • Device creates an open hotspot named CrossPoint-Reader.
  • The device shows a Wi-Fi QR code and URL QR code.
  • The fallback IP is typically 192.168.4.1.
  • /api/status returns "mode": "AP" and "rssi": 0.

Calibre Wireless

Calibre Wireless starts the same web server in STA mode and displays setup instructions plus WebSocket upload progress on the device screen.