A fork of https://github.com/crosspoint-reader/crosspoint-reader
1# Webserver Endpoints
2
3This document describes all HTTP and WebSocket endpoints available on the CrossPoint Reader webserver.
4
5- [Webserver Endpoints](#webserver-endpoints)
6 - [Overview](#overview)
7 - [HTTP Endpoints](#http-endpoints)
8 - [GET `/` - Home Page](#get----home-page)
9 - [GET `/files` - File Browser Page](#get-files---file-browser-page)
10 - [GET `/api/status` - Device Status](#get-apistatus---device-status)
11 - [GET `/api/files` - List Files](#get-apifiles---list-files)
12 - [POST `/upload` - Upload File](#post-upload---upload-file)
13 - [POST `/mkdir` - Create Folder](#post-mkdir---create-folder)
14 - [POST `/delete` - Delete File or Folder](#post-delete---delete-file-or-folder)
15 - [WebSocket Endpoint](#websocket-endpoint)
16 - [Port 81 - Fast Binary Upload](#port-81---fast-binary-upload)
17 - [Network Modes](#network-modes)
18 - [Station Mode (STA)](#station-mode-sta)
19 - [Access Point Mode (AP)](#access-point-mode-ap)
20 - [Notes](#notes)
21
22
23## Overview
24
25The CrossPoint Reader exposes a webserver for file management and device monitoring:
26
27- **HTTP Server**: Port 80
28- **WebSocket Server**: Port 81 (for fast binary uploads)
29
30---
31
32## HTTP Endpoints
33
34### GET `/` - Home Page
35
36Serves the home page HTML interface.
37
38**Request:**
39```bash
40curl http://crosspoint.local/
41```
42
43**Response:** HTML page (200 OK)
44
45---
46
47### GET `/files` - File Browser Page
48
49Serves the file browser HTML interface.
50
51**Request:**
52```bash
53curl http://crosspoint.local/files
54```
55
56**Response:** HTML page (200 OK)
57
58---
59
60### GET `/api/status` - Device Status
61
62Returns JSON with device status information.
63
64**Request:**
65```bash
66curl http://crosspoint.local/api/status
67```
68
69**Response (200 OK):**
70```json
71{
72 "version": "1.0.0",
73 "ip": "192.168.1.100",
74 "mode": "STA",
75 "rssi": -45,
76 "freeHeap": 123456,
77 "uptime": 3600
78}
79```
80
81| Field | Type | Description |
82| ---------- | ------ | --------------------------------------------------------- |
83| `version` | string | CrossPoint firmware version |
84| `ip` | string | Device IP address |
85| `mode` | string | `"STA"` (connected to WiFi) or `"AP"` (access point mode) |
86| `rssi` | number | WiFi signal strength in dBm (0 in AP mode) |
87| `freeHeap` | number | Free heap memory in bytes |
88| `uptime` | number | Seconds since device boot |
89
90---
91
92### GET `/api/files` - List Files
93
94Returns a JSON array of files and folders in the specified directory.
95
96**Request:**
97```bash
98# List root directory
99curl http://crosspoint.local/api/files
100
101# List specific directory
102curl "http://crosspoint.local/api/files?path=/Books"
103```
104
105**Query Parameters:**
106
107| Parameter | Required | Default | Description |
108| --------- | -------- | ------- | ---------------------- |
109| `path` | No | `/` | Directory path to list |
110
111**Response (200 OK):**
112```json
113[
114 {"name": "MyBook.epub", "size": 1234567, "isDirectory": false, "isEpub": true},
115 {"name": "Notes", "size": 0, "isDirectory": true, "isEpub": false},
116 {"name": "document.pdf", "size": 54321, "isDirectory": false, "isEpub": false}
117]
118```
119
120| Field | Type | Description |
121| ------------- | ------- | ---------------------------------------- |
122| `name` | string | File or folder name |
123| `size` | number | Size in bytes (0 for directories) |
124| `isDirectory` | boolean | `true` if the item is a folder |
125| `isEpub` | boolean | `true` if the file has `.epub` extension |
126
127**Notes:**
128- Hidden files (starting with `.`) are automatically filtered out
129- System folders (`System Volume Information`, `XTCache`) are hidden
130
131---
132
133### POST `/upload` - Upload File
134
135Uploads a file to the SD card via multipart form data.
136
137**Request:**
138```bash
139# Upload to root directory
140curl -X POST -F "file=@mybook.epub" http://crosspoint.local/upload
141
142# Upload to specific directory
143curl -X POST -F "file=@mybook.epub" "http://crosspoint.local/upload?path=/Books"
144```
145
146**Query Parameters:**
147
148| Parameter | Required | Default | Description |
149| --------- | -------- | ------- | ------------------------------- |
150| `path` | No | `/` | Target directory for the upload |
151
152**Response (200 OK):**
153```
154File uploaded successfully: mybook.epub
155```
156
157**Error Responses:**
158
159| Status | Body | Cause |
160| ------ | ----------------------------------------------- | --------------------------- |
161| 400 | `Failed to create file on SD card` | Cannot create file |
162| 400 | `Failed to write to SD card - disk may be full` | Write error during upload |
163| 400 | `Failed to write final data to SD card` | Error flushing final buffer |
164| 400 | `Upload aborted` | Client aborted the upload |
165| 400 | `Unknown error during upload` | Unspecified error |
166
167**Notes:**
168- Existing files with the same name will be overwritten
169- Uses a 4KB buffer for efficient SD card writes
170
171---
172
173### POST `/mkdir` - Create Folder
174
175Creates a new folder on the SD card.
176
177**Request:**
178```bash
179curl -X POST -d "name=NewFolder&path=/" http://crosspoint.local/mkdir
180```
181
182**Form Parameters:**
183
184| Parameter | Required | Default | Description |
185| --------- | -------- | ------- | ---------------------------- |
186| `name` | Yes | - | Name of the folder to create |
187| `path` | No | `/` | Parent directory path |
188
189**Response (200 OK):**
190```
191Folder created: NewFolder
192```
193
194**Error Responses:**
195
196| Status | Body | Cause |
197| ------ | ----------------------------- | ----------------------------- |
198| 400 | `Missing folder name` | `name` parameter not provided |
199| 400 | `Folder name cannot be empty` | Empty folder name |
200| 400 | `Folder already exists` | Folder with same name exists |
201| 500 | `Failed to create folder` | SD card error |
202
203---
204
205### POST `/delete` - Delete File or Folder
206
207Deletes a file or folder from the SD card.
208
209**Request:**
210```bash
211# Delete a file
212curl -X POST -d "path=/Books/mybook.epub&type=file" http://crosspoint.local/delete
213
214# Delete an empty folder
215curl -X POST -d "path=/OldFolder&type=folder" http://crosspoint.local/delete
216```
217
218**Form Parameters:**
219
220| Parameter | Required | Default | Description |
221| --------- | -------- | ------- | -------------------------------- |
222| `path` | Yes | - | Path to the item to delete |
223| `type` | No | `file` | Type of item: `file` or `folder` |
224
225**Response (200 OK):**
226```
227Deleted successfully
228```
229
230**Error Responses:**
231
232| Status | Body | Cause |
233| ------ | --------------------------------------------- | ----------------------------- |
234| 400 | `Missing path` | `path` parameter not provided |
235| 400 | `Cannot delete root directory` | Attempted to delete `/` |
236| 400 | `Folder is not empty. Delete contents first.` | Non-empty folder |
237| 403 | `Cannot delete system files` | Hidden file (starts with `.`) |
238| 403 | `Cannot delete protected items` | Protected system folder |
239| 404 | `Item not found` | Path does not exist |
240| 500 | `Failed to delete item` | SD card error |
241
242**Protected Items:**
243- Files/folders starting with `.`
244- `System Volume Information`
245- `XTCache`
246
247---
248
249## WebSocket Endpoint
250
251### Port 81 - Fast Binary Upload
252
253A WebSocket endpoint for high-speed binary file uploads. More efficient than HTTP multipart for large files.
254
255**Connection:**
256```
257ws://crosspoint.local:81/
258```
259
260**Protocol:**
261
2621. **Client** sends TEXT message: `START:<filename>:<size>:<path>`
2632. **Server** responds with TEXT: `READY`
2643. **Client** sends BINARY messages with file data chunks
2654. **Server** sends TEXT progress updates: `PROGRESS:<received>:<total>`
2665. **Server** sends TEXT when complete: `DONE` or `ERROR:<message>`
267
268**Example Session:**
269
270```
271Client -> "START:mybook.epub:1234567:/Books"
272Server -> "READY"
273Client -> [binary chunk 1]
274Client -> [binary chunk 2]
275Server -> "PROGRESS:65536:1234567"
276Client -> [binary chunk 3]
277...
278Server -> "PROGRESS:1234567:1234567"
279Server -> "DONE"
280```
281
282**Error Messages:**
283
284| Message | Cause |
285| --------------------------------- | ---------------------------------- |
286| `ERROR:Failed to create file` | Cannot create file on SD card |
287| `ERROR:Invalid START format` | Malformed START message |
288| `ERROR:No upload in progress` | Binary data received without START |
289| `ERROR:Write failed - disk full?` | SD card write error |
290
291**Example with `websocat`:**
292```bash
293# Interactive session
294websocat ws://crosspoint.local:81
295
296# Then type:
297START:mybook.epub:1234567:/Books
298# Wait for READY, then send binary data
299```
300
301**Notes:**
302- Progress updates are sent every 64KB or at completion
303- Disconnection during upload will delete the incomplete file
304- Existing files with the same name will be overwritten
305
306---
307
308## Network Modes
309
310The device can operate in two network modes:
311
312### Station Mode (STA)
313- Device connects to an existing WiFi network
314- IP address assigned by router/DHCP
315- `mode` field in `/api/status` returns `"STA"`
316- `rssi` field shows signal strength
317
318### Access Point Mode (AP)
319- Device creates its own WiFi hotspot
320- Default IP is typically `192.168.4.1`
321- `mode` field in `/api/status` returns `"AP"`
322- `rssi` field returns `0`
323
324---
325
326## Notes
327
328- 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/`).
329- All paths on the SD card start with `/`
330- Trailing slashes are automatically stripped (except for root `/`)
331- The webserver uses chunked transfer encoding for file listings