Read a pin from a web page

After the license on your Docker server is valid, a page can read one virtual pin over HTTP or HTTPS. The path is /public/, then the device key from the dashboard, then the pin. The address only reads. It does not write to the board.

JSON

This is the default. V0 is virtual pin 0. The letter can be lowercase, and the number alone is the same pin. Pins run from 0 through 127.

https://your-server.example/public/bx_your_device_key/V0
https://your-server.example/public/bx_your_device_key/v12
https://your-server.example/public/bx_your_device_key/40

A JSON body looks like this when pin 0 holds 77. pin is a number. value is the string the board last wrote.

{"pin":0,"value":"77"}

Plain text

Three options return only the value, with no JSON around it. For the same pin, the body is 77.

Add .txt to the pin:

https://your-server.example/public/bx_your_device_key/V0.txt

Or add ?format=text. This works with V, v, or the bare number:

https://your-server.example/public/bx_your_device_key/V0?format=text
https://your-server.example/public/bx_your_device_key/v12?format=text
https://your-server.example/public/bx_your_device_key/40?format=text

Or send the header Accept: text/plain on the JSON address. The path can stay /V0 and the body is still only the value.

GET /public/bx_your_device_key/V0 HTTP/1.1
Host: your-server.example
Accept: text/plain

Read it from a page

A page on another site can fetch the pin. The server allows any origin on this path.

const json = await fetch("https://your-server.example/public/bx_your_device_key/V0");
const data = await json.json();
// data.pin is 0 and data.value is "77"

const plain = await fetch("https://your-server.example/public/bx_your_device_key/V0.txt");
const value = await plain.text();
// value is "77"

What each result means

• A valid read is status 200. An empty value means that pin has not been written yet.
• A missing or expired license is status 403. JSON is {"error":"A valid license is required","pin":0,"value":""}. Plain text is an empty body.
• An unknown device key is status 404 with {"error":"Unknown device key"}.
• A pin above 127, a path that is not three parts, or a key that is not bx_ plus 16 to 80 hex characters is status 404 with {"error":"Pin address not found"}.
• Anything other than GET is status 405 with {"error":"Read only"}.
• More than 120 reads in a minute from one address is status 429 with {"error":"Too many reads"}. Plain text is an empty body.

Anyone who has the URL can read that pin, so treat the device key like a password. HTTP on port 80 redirects to HTTPS.