webserver.md
1 # Web Server Guide 2 3 This guide explains how to connect your DWS SignalOS to WiFi and use the built-in web server to upload EPUB files from your computer or phone. 4 5 ## Overview 6 7 DWS SignalOS includes a built-in web server that allows you to: 8 9 - Upload EPUB files wirelessly from any device on the same WiFi network 10 - Browse and manage files on your device's SD card 11 - Create folders to organize your ebooks 12 - Delete files and folders 13 14 ## Prerequisites 15 16 - Your DWS SignalOS device 17 - A WiFi network 18 - A computer, phone, or tablet connected to the **same WiFi network** 19 20 --- 21 22 ## Step 1: Accessing File Transfer 23 24 1. From the Home screen, press the **Left** button (or from the file browser, select **Sync**) 25 2. Select **File Transfer** 26 3. The device will automatically start scanning for available networks 27 28 --- 29 30 ## Step 2: Connecting to WiFi 31 32 ### Viewing Available Networks 33 34 Once the scan completes, you'll see a list of available WiFi networks with the following indicators: 35 36 - **Signal strength bars** (`||||`, `|||`, `||`, `|`) - Shows connection quality 37 - **`*` symbol** - Indicates the network is password-protected (encrypted) 38 - **`+` symbol** - Indicates you have previously saved credentials for this network 39 40 <img src="./images/wifi/wifi_networks.jpeg" height="500"> 41 42 ### Selecting a Network 43 44 1. Use the **Left/Right** (or **Volume Up/Down**) buttons to navigate through the network list 45 2. Press **Confirm** to select the highlighted network 46 47 ### Entering Password (for encrypted networks) 48 49 If the network requires a password: 50 51 1. An on-screen keyboard will appear with a full character grid 52 2. The keyboard is organized in zones: 53 - **Rows 1-3:** Lowercase letters (a-z) and common symbols (. - _ @) 54 - **Rows 4-6:** Uppercase letters (A-Z) and symbols (! # $ %) 55 - **Row 7:** Numbers (0-9) 56 - **Row 8:** Additional symbols (^ & * ( ) + [ ] \) 57 - **Bottom row:** SPACE and BACKSPACE controls 58 3. Use **Up/Down/Left/Right** to navigate the grid 59 4. Press **Confirm** to enter the selected character 60 5. Press **Back** to cancel and return 61 62 **Note:** If you've previously connected to this network, the saved password will be used automatically. 63 64 ### Connection Process 65 66 The device will display "Connecting..." while establishing the connection. This typically takes 5-10 seconds. 67 68 ### Saving Credentials 69 70 If this is a new network, you'll be prompted to save the password: 71 72 - Select **Yes** to save credentials for automatic connection next time (NOTE: These are stored in plaintext on the device's SD card. Do not use this for sensitive networks.) 73 - Select **No** to connect without saving 74 75 --- 76 77 ## Step 3: Connection Success 78 79 Once connected, the screen will display: 80 81 - **Network name** (SSID) 82 - **IP Address** (e.g., `192.168.1.102`) 83 - **Web server URL** (e.g., `http://192.168.1.102/`) 84 85 <img src="./images/wifi/wifi_connected.jpeg" height="500"> 86 87 **Important:** Make note of the IP address - you'll need this to access the web interface from your computer or phone. 88 89 --- 90 91 ## Step 4: Accessing the Web Interface 92 93 ### From a Computer 94 95 1. Ensure your computer is connected to the **same WiFi network** as your DWS SignalOS 96 2. Open any web browser (Chrome is recommended) 97 3. Type the IP address shown on your device into the browser's address bar 98 - Example: `http://192.168.1.102/` 99 4. Press Enter 100 101 ### From a Phone or Tablet 102 103 1. Ensure your phone/tablet is connected to the **same WiFi network** as your DWS SignalOS 104 2. Open your mobile browser (Safari, Chrome, etc.) 105 3. Type the IP address into the address bar 106 - Example: `http://192.168.1.102/` 107 4. Tap Go 108 109 --- 110 111 ## Step 5: Using the Web Interface 112 113 ### Home Page 114 115 The home page displays: 116 117 - Device status and version information 118 - WiFi connection status 119 - Current IP address 120 - Available memory 121 122 Navigation links: 123 124 - **Home** - Returns to the status page 125 - **File Manager** - Access file management features 126 127 <img src="./images/wifi/webserver_homepage.png" width="600"> 128 129 ### File Manager 130 131 Click **File Manager** to access file management features. 132 133 #### Browsing Files 134 135 - The file manager displays all files and folders on your SD card 136 - **Folders** are highlighted in yellow with a 📁 icon 137 - **EPUB files** are highlighted in green with a 📗 icon 138 - Click on a folder name to navigate into it 139 - Use the breadcrumb navigation at the top to go back to parent folders 140 141 <img src="./images/wifi/webserver_files.png" width="600"> 142 143 #### Uploading EPUB Files 144 145 1. Click the **+ Add** button in the top-right corner 146 2. Select **Upload eBook** from the dropdown menu 147 3. Click **Choose File** and select an `.epub` file from your device 148 4. Click **Upload** 149 5. A progress bar will show the upload status 150 6. The page will automatically refresh when the upload is complete 151 152 **Note:** Only `.epub` files are accepted. Other file types will be rejected. 153 154 <img src="./images/wifi/webserver_upload.png" width="600"> 155 156 #### Creating Folders 157 158 1. Click the **+ Add** button in the top-right corner 159 2. Select **New Folder** from the dropdown menu 160 3. Enter a folder name (letters, numbers, underscores, and hyphens only) 161 4. Click **Create Folder** 162 163 This is useful for organizing your ebooks by genre, author, or series. 164 165 #### Deleting Files and Folders 166 167 1. Click the **🗑️** (trash) icon next to any file or folder 168 2. Confirm the deletion in the popup dialog 169 3. Click **Delete** to permanently remove the item 170 171 **Warning:** Deletion is permanent and cannot be undone! 172 173 **Note:** Folders must be empty before they can be deleted. 174 175 --- 176 177 ## Troubleshooting 178 179 ### Cannot See the Device on the Network 180 181 **Problem:** Browser shows "Cannot connect" or "Site can't be reached" 182 183 **Solutions:** 184 185 1. Verify both devices are on the **same WiFi network** 186 - Check your computer/phone WiFi settings 187 - Confirm the DWS SignalOS shows "Connected" status 188 2. Double-check the IP address 189 - Make sure you typed it correctly 190 - Include `http://` at the beginning 191 3. Try disabling VPN if you're using one 192 4. Some networks have "client isolation" enabled - check with your network administrator 193 194 ### Connection Drops or Times Out 195 196 **Problem:** WiFi connection is unstable 197 198 **Solutions:** 199 200 1. Move closer to the WiFi router 201 2. Check signal strength on the device (should be at least `||` or better) 202 3. Avoid interference from other devices 203 4. Try a different WiFi network if available 204 205 ### Upload Fails 206 207 **Problem:** File upload doesn't complete or shows an error 208 209 **Solutions:** 210 211 1. Ensure the file is a valid `.epub` file 212 2. Check that the SD card has enough free space 213 3. Try uploading a smaller file first to test 214 4. Refresh the browser page and try again 215 216 ### Saved Password Not Working 217 218 **Problem:** Device fails to connect with saved credentials 219 220 **Solutions:** 221 222 1. When connection fails, you'll be prompted to "Forget Network" 223 2. Select **Yes** to remove the saved password 224 3. Reconnect and enter the password again 225 4. Choose to save the new password 226 227 --- 228 229 ## Security Notes 230 231 - The web server runs on port 80 (standard HTTP) 232 - **No authentication is required** - anyone on the same network can access the interface 233 - The web server is only accessible while the WiFi screen shows "Connected" 234 - The web server automatically stops when you exit the WiFi screen 235 - For security, only use on trusted private networks 236 237 --- 238 239 ## Technical Details 240 241 - **Supported WiFi:** 2.4GHz networks (802.11 b/g/n) 242 - **Web Server Port:** 80 (HTTP) 243 - **Maximum Upload Size:** Limited by available SD card space 244 - **Supported File Format:** `.epub` only 245 - **Browser Compatibility:** All modern browsers (Chrome, Firefox, Safari, Edge) 246 247 --- 248 249 ## Tips and Best Practices 250 251 1. **Organize with folders** - Create folders before uploading to keep your library organized 252 2. **Check signal strength** - Stronger signals (`|||` or `||||`) provide faster, more reliable uploads 253 3. **Upload multiple files** - You can upload files one at a time; the page refreshes after each upload 254 4. **Use descriptive names** - Name your folders clearly (e.g., "SciFi", "Mystery", "Non-Fiction") 255 5. **Keep credentials saved** - Save your WiFi password for quick reconnection in the future 256 6. **Exit when done** - Press **Back** to exit the WiFi screen and save battery 257 258 --- 259 260 ## Exiting WiFi Mode 261 262 When you're finished uploading files: 263 264 1. Press the **Back** button on your DWS SignalOS 265 2. The web server will automatically stop 266 3. WiFi will disconnect 267 4. **The device will automatically restart** to reclaim memory 268 269 > **Note:** The automatic restart is required because the ESP32's WiFi stack fragments memory in a way that cannot be recovered. Without this restart, XTC books may fail to load with a "Memory error". The restart is quick and your uploaded files will be immediately available in the file browser. 270 271 --- 272 273 ## Related Documentation 274 275 - [User Guide](user_guide.md) - General device operation 276 - [Customization Guide](customization.md) - Custom themes and fonts 277 - [README](../README.md) - Project overview and features