Serial API Documentation

Basics

  • You can connect to a PiShock with V3 firmware via serial at, 115200 baud, 8n1
  • The device will have a USB VID of 0x1A86 and PID of 0x7523 (Next hardware) or 0x55D4 (Lite hardware)
  • All commands are in JSON format, terminated by a line end ( \n, \r, or \r\n ).
  • There is no "reply" sent by the PiShock, other than the TEREMINALINFO described below.
  • The format for all commands is {"cmd": "..."} with an optional {"cmd": "...", "value": "..."}.

Network Management

Add New Network

Adds a new network to the networks saved on the PiShock. The PiShock will send a TERMINALINFO block (see below) and restart.

  • Command: addnetwork
  • Value: {"ssid": "...", "password": "..."}
  • Example: {"cmd": "addnetwork", "value": {"ssid": "My WiFi", "password": "hunter2"}}

Remove Network

Remove a network from the networks saved on the PiShock. The PiShock will send a TERMINALINFO block (see below).

  • Command: removenetwork
  • Value: The SSID as string
  • Example: {"cmd": "removenetwork", "value": "My WiFi"}

Temporarily Connect To Network

Temporarily ties to connect to the given network without saving it.

  • Command: connect
  • Value: {"ssid": "...", "password": "..."}
  • Example: {"cmd": "connect", "value": {"ssid": "My WiFi", "password": "hunter2"}}

Other

Restarting

Reboots the PiShock

  • Command: restart
  • No value
  • Example: {"cmd": "restart"}

Getting Info

Generates a TERMINALINFO block.

  • Command: info
  • No value
  • Example: {"cmd": "info"}
    The PiShock will reply with a JSON object prefixed by TERMINALINFO:, looking like:
{
    "version": "3.1.1.231119.1556",    // The running firmware version
    "type": 4,                         // Hardware type: 3 for Next, 4 for Lite
    "connected": false,                // Is the PiShock connected to the server?
    "clientId": 621,                   // The ID of the PiShock (as shown on the website)
    "wifi": "My WiFi",                 // The WiFi the PiShock is connected to
    "server": "eu1.pishock.com",       // The server the PiShock is connected to
    "macAddress": "0C:B8:15:AB:CD:EF", // The MAC of the PiShock
    "shockers": [                      // The shockers this PiShock knows about
        {
            "id": 420,                 // The shocker ID (as shown on the website)
            "type": 1,                 // 0 for Petrainer (old) 1 for SmallOne (new)
            "paused": false            // Whether this shocker is currently paused
        }
    ],
    "networks": [                      // The WiFi networks configured/saved on the device
        {
            "ssid": "My WiFi",
            "password": "hunter2"
        },
        {
            "ssid": "PiShock",         // This one comes preconfigured
            "password": "Zappy454"
        }
    ],
    "otk": "e71d7b27-dc38-4774-bafc-c427757f0134",  // The one-time key which was used for pairing
    "claimed": true,                   // Whether this PiShock was claimed via the OTK
    "isDev": false,                    // Whether the PiShock is configured to connect to a dev server
    "publisher": false,                // Whether the PiShock is connected as publisher
    "polled": true,                    // Whether the PiShock has polled the server
    "subscriber": true,                // Whether the PiShock is connected as subscriber
    "publicIp": "203.0.113.69",        // The public IP of the PiShock
    "internet": true,                  // Whether we have an internet connection
    "ownerId": 6969                    // The ID of the user that claimed the PiShock
}

Shocking

  • Command: "operate"
  • Value: {"id": "...", "op": "...", "duration": ..., "intensity": ...}, where:
    • "id" is the ID of the shocker to operate, as shown on the website or in the TERMINALINFO block above
    • "op" is either "shock", "vibrate", "beep", or "end" (end the current operation prematurely). These may each be abbreviated to their first letter.
    • "duration" is the duration in milliseconds, between 0 and 2³². Should be 0 for "end".
    • "intensity" is the intensity in %, i.e. between 0 and 100. Should be absent (or 0) for "beep" and "end".
  • Examples:
    • 20% 1s shock: {"cmd": "operate", "value": {"id": 420, "op": "shock", "duration": 1000, "intensity": 20}}
    • 100% 300ms vibration:{"cmd": "operate", "value": {"id": 420, "op": "vibrate", "duration": 300, "intensity": 100}}
    • 1s beep: {"cmd": "operate", "value": {"id": 420, "op": "beep", "duration": 1000}}
    • End current operation: {"cmd": "operate", "value": {"id": 420, "op": "end", "duration": 0}}