A fork of https://github.com/crosspoint-reader/crosspoint-reader

Fork 0

crosspoint-reader docs webserver-endpoints.md

12 kB

Markdown

at records-reader

Justin Mitchell · feat: Add TrueType fonts on PSRAM boards (#3646) · 2w ago

aaf68379

Webserver Endpoints #

This document describes the HTTP, WebSocket, WebDAV, and discovery endpoints available while CrossPoint Reader 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": "Reader Font Size",
  "category": "Reader",
  "type": "enum",
  "value": 1,
  "options": ["12 pt", "14 pt", "16 pt", "18 pt"]
}

value is always an index into options, never the option's text. The fontSize options depend on the selected family. A .cpfont family installed at 10/12/14 pt offers those three sizes. TTF/OTF/TTC families offer the standard 12/14/16/18 pt sizes. The fontFamily and dictionaryName options also depend on the SD card contents.

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.

`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. On devices that load TTF/OTF/TTC files, these families appear with sizes: [0]. The 0 means that the font file has no fixed point size; the reader offers 12, 14, 16, and 18 pt.

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.

This endpoint removes family subfolders. To remove a loose TTF/OTF/TTC file from a font root, delete the file from the SD card instead.

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:

Client sends text: START:<filename>:<size>:<path>
Server replies READY
Client sends binary chunks
Server sends PROGRESS:<received>:<total> every 64 KB or at completion
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.

Webserver Endpoints #

HTTP Pages #

Device Status #

GET /api/status #

File Management #

GET /api/files #

GET /download #

POST /upload #

POST /mkdir #

POST /rename #

POST /move #

POST /delete #

Settings API #

GET /api/settings #

POST /api/settings #

Font Management API #

GET /api/fonts #

POST /api/fonts/upload #

POST /api/fonts/delete #

OPDS Server API #

GET /api/opds #

POST /api/opds #

POST /api/opds/delete #

Wi-Fi Credential API #

GET /api/wifi #

POST /api/wifi #

POST /api/wifi/delete #

WebSocket Upload #

Port 81 #

WebDAV #

UDP Discovery #

Network Modes #

Station Mode (STA) #

Access Point Mode (AP) #

Calibre Wireless #

`GET /api/status` #

`GET /api/files` #

`GET /download` #

`POST /upload` #

`POST /mkdir` #

`POST /rename` #

`POST /move` #

`POST /delete` #

`GET /api/settings` #

`POST /api/settings` #

`GET /api/fonts` #

`POST /api/fonts/upload` #

`POST /api/fonts/delete` #

`GET /api/opds` #

`POST /api/opds` #

`POST /api/opds/delete` #

`GET /api/wifi` #

`POST /api/wifi` #

`POST /api/wifi/delete` #