Pocket server

Install

Click the button below to flash your ESP8266 with the pocket server firmware (supported on Chrome-based browsers only).

Run

After flashing and rebooting your ESP8266, connect to the Wi-Fi network prefixed with "pocket-server" using default password "password123". On some devices, the admin page will automatically appear. If not, you can navigate to http://192.168.4.1.

Once on the admin page, upload any .html file. Downloadable examples below. Any future devices connecting to your pocket server will see this page by default.

To get back to the admin page, navigate to http://192.168.4.1/admin.

Example applications

API Documentation

The API allows you to interact with the pocket server to manage files, control GPIO pins, and communicate via WebSockets.

1. File Management

List Files: retrieve a list of all files stored on the device's filesystem.

• URL: /files
• Method: GET
• Example curl request: curl http://192.168.4.1/files
• Response: JSON array of file objects. Example:

  [
    {
      "name": "index.html",
      "size": 1024
    },
    {
      "name": "style.css",
      "size": 500
    }
  ]

Upload File: uploads a file to the device. The file will be saved with its original filename.

• URL: /files
• Method: POST
• Content-Type: multipart/form-data
• Form Data:
  • upload: The file to upload.
• Example curl request: curl -X POST -F "upload=@example.html" http://192.168.4.1/files
• Response: 200 OK upon success.

Set Home Page: uploads a file and saves it as index.html, effectively setting it as the homepage of the device.

• URL: /sethome
• Method: POST
• Content-Type: multipart/form-data
• Form Data:
  • upload: The file to upload (will be renamed to index.html).
• Example curl request: curl -X POST -F "upload=@index.html" http://192.168.4.1/sethome
• Response: 200 OK upon success.

Delete File: deletes a specific file from the filesystem.

• URL: /files/{filename}
• Method: DELETE
• Example curl request: curl -X DELETE http://192.168.4.1/files/example.html
• Response:
  • 200 OK: File deleted successfully.
  • 404 Not Found: File does not exist.
  • 500 Internal Server Error: Deletion failed.

Clear Storage: deletes all files from the filesystem (excluding system files if any are protected, though currently it wipes everything visible).

• URL: /storage
• Method: DELETE
• Example curl request: curl -X DELETE http://192.168.4.1/storage
• Response:
  • 200 OK: All files deleted.

2. GPIO Control

Read Pin State: reads the current digital state of a GPIO pin.

• URL: /pin/{pin_number}
• Method: GET
• Parameters:
  • pin_number: The GPIO pin number (e.g., 0, 2, 4, 5, 12, 13, 14, 15, 16).
• Example curl request: curl http://192.168.4.1/pin/5
• Response: JSON object. Example:

  {
    "pin": 5,
    "value": 1  // 1 for HIGH, 0 for LOW
  }

• Error Response:
  • 400 Bad Request: Invalid or unsafe pin number.

Control Pin: sets the mode and/or digital value of a GPIO pin.

• URL: /pin/{pin_number}
• Method: POST
• Content-Type: application/json
• Body: JSON object (all fields are optional). Example:

  {
    "mode": "OUTPUT",      // "INPUT", "OUTPUT", or "INPUT_PULLUP"
    "value": 1             // 0 (LOW) or 1 (HIGH)
  }

• Example curl request: curl -X POST -H "Content-Type: application/json" -d '{"mode":"OUTPUT","value":1}' http://192.168.4.1/pin/5
• Response: JSON object representing the new state. Example:

  {
    "pin": 5,
    "value": 1
  }

• Error Response:
  • 400 Bad Request: Invalid pin, invalid JSON, or no body received.

3. WebSocket

WebSocket Connection: connect to the WebSocket for real-time interaction. Messages sent to this endpoint are broadcast to all other connected clients.

• URL: /websocket
• Protocol: ws://

4. Administration

Admin Page: access the built-in file management interface.

• URL: /admin
• Method: GET
• Description: Provides a web interface to list, upload, delete files, and set the homepage.