A fork of https://github.com/crosspoint-reader/crosspoint-reader
docs: Add detailed webserver documentation (#446)
## More detailed documentation
* **What is the goal of this PR?**
Add more information about the exposed webserver.
* **What changes are included?**
Detailed documentation for the webserver endpoints
(`./docs/webserver-endpoints.md`)
Adding a table of content so it is easier to navigate directly to the
section you're interested on (Almost all `.md` files or at least all
those relevant)
## Additional Context
Not sure if this would get accepted but I thought it might be useful for
those trying to create separate apps that would sync files to the
device. It was at least to me trying to upload files using python as
stated
[here](https://github.com/crosspoint-reader/crosspoint-reader/discussions/434#discussioncomment-15545349)
---
### AI Usage
While CrossPoint doesn't have restrictions on AI tools in contributing,
please be transparent about their usage as it
helps set the right context for reviewers.
Did you use AI tools to help write this code? _**PARTIALLY**_
authored by
Juan Biondi
and committed by
GitHub
e3d6e326
d399afb5
+411
-83
+21
USER_GUIDE.md
+21
USER_GUIDE.md
···
2
2
3
3
Welcome to the **CrossPoint** firmware. This guide outlines the hardware controls, navigation, and reading features of the device.
4
4
5
+
- [CrossPoint User Guide](#crosspoint-user-guide)
6
+
- [1. Hardware Overview](#1-hardware-overview)
7
+
- [Button Layout](#button-layout)
8
+
- [2. Power \& Startup](#2-power--startup)
9
+
- [Power On / Off](#power-on--off)
10
+
- [First Launch](#first-launch)
11
+
- [3. Screens](#3-screens)
12
+
- [3.1 Home Screen](#31-home-screen)
13
+
- [3.2 Book Selection](#32-book-selection)
14
+
- [3.3 Reading Mode](#33-reading-mode)
15
+
- [3.4 File Upload Screen](#34-file-upload-screen)
16
+
- [3.5 Settings](#35-settings)
17
+
- [3.6 Sleep Screen](#36-sleep-screen)
18
+
- [4. Reading Mode](#4-reading-mode)
19
+
- [Page Turning](#page-turning)
20
+
- [Chapter Navigation](#chapter-navigation)
21
+
- [System Navigation](#system-navigation)
22
+
- [5. Chapter Selection Screen](#5-chapter-selection-screen)
23
+
- [6. Current Limitations \& Roadmap](#6-current-limitations--roadmap)
24
+
25
+
5
26
## 1. Hardware Overview
6
27
7
28
The device utilises the standard buttons on the Xtink X4 (in the same layout as the manufacturer firmware, by default):
+57
docs/troubleshooting.md
+57
docs/troubleshooting.md
···
1
+
# Troubleshooting
2
+
3
+
This document show most common issues and possible solutions while using the device features.
4
+
5
+
- [Troubleshooting](#troubleshooting)
6
+
- [Cannot See the Device on the Network](#cannot-see-the-device-on-the-network)
7
+
- [Connection Drops or Times Out](#connection-drops-or-times-out)
8
+
- [Upload Fails](#upload-fails)
9
+
- [Saved Password Not Working](#saved-password-not-working)
10
+
11
+
### Cannot See the Device on the Network
12
+
13
+
**Problem:** Browser shows "Cannot connect" or "Site can't be reached"
14
+
15
+
**Solutions:**
16
+
17
+
1. Verify both devices are on the **same WiFi network**
18
+
- Check your computer/phone WiFi settings
19
+
- Confirm the CrossPoint Reader shows "Connected" status
20
+
2. Double-check the IP address
21
+
- Make sure you typed it correctly
22
+
- Include `http://` at the beginning
23
+
3. Try disabling VPN if you're using one
24
+
4. Some networks have "client isolation" enabled - check with your network administrator
25
+
26
+
### Connection Drops or Times Out
27
+
28
+
**Problem:** WiFi connection is unstable
29
+
30
+
**Solutions:**
31
+
32
+
1. Move closer to the WiFi router
33
+
2. Check signal strength on the device (should be at least `||` or better)
34
+
3. Avoid interference from other devices
35
+
4. Try a different WiFi network if available
36
+
37
+
### Upload Fails
38
+
39
+
**Problem:** File upload doesn't complete or shows an error
40
+
41
+
**Solutions:**
42
+
43
+
1. Ensure the file is a valid `.epub` file
44
+
2. Check that the SD card has enough free space
45
+
3. Try uploading a smaller file first to test
46
+
4. Refresh the browser page and try again
47
+
48
+
### Saved Password Not Working
49
+
50
+
**Problem:** Device fails to connect with saved credentials
51
+
52
+
**Solutions:**
53
+
54
+
1. When connection fails, you'll be prompted to "Forget Network"
55
+
2. Select **Yes** to remove the saved password
56
+
3. Reconnect and enter the password again
57
+
4. Choose to save the new password
+331
docs/webserver-endpoints.md
+331
docs/webserver-endpoints.md
···
1
+
# Webserver Endpoints
2
+
3
+
This 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
+
25
+
The 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
+
36
+
Serves the home page HTML interface.
37
+
38
+
**Request:**
39
+
```bash
40
+
curl http://crosspoint.local/
41
+
```
42
+
43
+
**Response:** HTML page (200 OK)
44
+
45
+
---
46
+
47
+
### GET `/files` - File Browser Page
48
+
49
+
Serves the file browser HTML interface.
50
+
51
+
**Request:**
52
+
```bash
53
+
curl http://crosspoint.local/files
54
+
```
55
+
56
+
**Response:** HTML page (200 OK)
57
+
58
+
---
59
+
60
+
### GET `/api/status` - Device Status
61
+
62
+
Returns JSON with device status information.
63
+
64
+
**Request:**
65
+
```bash
66
+
curl 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
+
94
+
Returns a JSON array of files and folders in the specified directory.
95
+
96
+
**Request:**
97
+
```bash
98
+
# List root directory
99
+
curl http://crosspoint.local/api/files
100
+
101
+
# List specific directory
102
+
curl "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
+
135
+
Uploads a file to the SD card via multipart form data.
136
+
137
+
**Request:**
138
+
```bash
139
+
# Upload to root directory
140
+
curl -X POST -F "file=@mybook.epub" http://crosspoint.local/upload
141
+
142
+
# Upload to specific directory
143
+
curl -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
+
```
154
+
File 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
+
175
+
Creates a new folder on the SD card.
176
+
177
+
**Request:**
178
+
```bash
179
+
curl -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
+
```
191
+
Folder 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
+
207
+
Deletes a file or folder from the SD card.
208
+
209
+
**Request:**
210
+
```bash
211
+
# Delete a file
212
+
curl -X POST -d "path=/Books/mybook.epub&type=file" http://crosspoint.local/delete
213
+
214
+
# Delete an empty folder
215
+
curl -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
+
```
227
+
Deleted 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
+
253
+
A WebSocket endpoint for high-speed binary file uploads. More efficient than HTTP multipart for large files.
254
+
255
+
**Connection:**
256
+
```
257
+
ws://crosspoint.local:81/
258
+
```
259
+
260
+
**Protocol:**
261
+
262
+
1. **Client** sends TEXT message: `START:<filename>:<size>:<path>`
263
+
2. **Server** responds with TEXT: `READY`
264
+
3. **Client** sends BINARY messages with file data chunks
265
+
4. **Server** sends TEXT progress updates: `PROGRESS:<received>:<total>`
266
+
5. **Server** sends TEXT when complete: `DONE` or `ERROR:<message>`
267
+
268
+
**Example Session:**
269
+
270
+
```
271
+
Client -> "START:mybook.epub:1234567:/Books"
272
+
Server -> "READY"
273
+
Client -> [binary chunk 1]
274
+
Client -> [binary chunk 2]
275
+
Server -> "PROGRESS:65536:1234567"
276
+
Client -> [binary chunk 3]
277
+
...
278
+
Server -> "PROGRESS:1234567:1234567"
279
+
Server -> "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
294
+
websocat ws://crosspoint.local:81
295
+
296
+
# Then type:
297
+
START: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
+
310
+
The 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
+2
-83
docs/webserver.md
+2
-83
docs/webserver.md
···
172
172
173
173
## Command Line File Management
174
174
175
-
For power users, you can manage files directly from your terminal using `curl` while the device is in File Upload mode.
176
-
177
-
### Uploading a File
178
-
To upload a file to the root directory, use the following command:
179
-
```bash
180
-
curl -F "file=@book.epub" "http://crosspoint.local/upload?path=/"
181
-
```
182
-
183
-
* **`-F "file=@filename"`**: Points to the local file on your computer.
184
-
* **`path=/`**: The destination folder on the device SD card.
185
-
186
-
### Deleting a File
187
-
188
-
To delete a specific file, provide the full path on the SD card:
189
-
190
-
```bash
191
-
curl -F "path=/folder/file.epub" "http://crosspoint.local/delete"
192
-
```
193
-
194
-
### Advanced Flags
195
-
196
-
For more reliable transfers of large EPUB files, consider adding these flags:
197
-
198
-
* `-#`: Shows a simple progress bar.
199
-
* `--connect-timeout 30`: Limits how long curl waits to establish a connection (in seconds).
200
-
* `--max-time 300`: Sets a maximum duration for the entire transfer (5 minutes).
201
-
202
-
> [!NOTE]
203
-
> 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/`).
204
-
205
-
---
206
-
207
-
## Troubleshooting
208
-
209
-
### Cannot See the Device on the Network
210
-
211
-
**Problem:** Browser shows "Cannot connect" or "Site can't be reached"
212
-
213
-
**Solutions:**
214
-
215
-
1. Verify both devices are on the **same WiFi network**
216
-
- Check your computer/phone WiFi settings
217
-
- Confirm the CrossPoint Reader shows "Connected" status
218
-
2. Double-check the IP address
219
-
- Make sure you typed it correctly
220
-
- Include `http://` at the beginning
221
-
3. Try disabling VPN if you're using one
222
-
4. Some networks have "client isolation" enabled - check with your network administrator
223
-
224
-
### Connection Drops or Times Out
225
-
226
-
**Problem:** WiFi connection is unstable
227
-
228
-
**Solutions:**
229
-
230
-
1. Move closer to the WiFi router
231
-
2. Check signal strength on the device (should be at least `||` or better)
232
-
3. Avoid interference from other devices
233
-
4. Try a different WiFi network if available
234
-
235
-
### Upload Fails
236
-
237
-
**Problem:** File upload doesn't complete or shows an error
238
-
239
-
**Solutions:**
240
-
241
-
1. Ensure the file is a valid `.epub` file
242
-
2. Check that the SD card has enough free space
243
-
3. Try uploading a smaller file first to test
244
-
4. Refresh the browser page and try again
245
-
246
-
### Saved Password Not Working
247
-
248
-
**Problem:** Device fails to connect with saved credentials
249
-
250
-
**Solutions:**
251
-
252
-
1. When connection fails, you'll be prompted to "Forget Network"
253
-
2. Select **Yes** to remove the saved password
254
-
3. Reconnect and enter the password again
255
-
4. Choose to save the new password
256
-
257
-
---
175
+
For power users, you can manage files directly from your terminal using `curl` while the device is in File Upload mode a detailed documentation can be found [here](./webserver-endpoints.md).
258
176
259
177
## Security Notes
260
178
···
303
221
## Related Documentation
304
222
305
223
- [User Guide](../USER_GUIDE.md) - General device operation
224
+
- [Troubleshooting](./troubleshooting.md) - Troubleshooting
306
225
- [README](../README.md) - Project overview and features