Brew Bubbles API

Brewbubbles stores and communicates with external agents via JSON. This document details those mechanics.

Configuration Storage

The device likewise stores its configuration in JSON within SPIFFS. The application stores configuration data in the following format:

        "name":"Fermenter 1",

These keys represent the following settings:


ssid: The AP name (SSID) which broadcasts when the controller is in AP mode

appwd: The AP password required to connect to the AP

The mDNS hostname used by the controller

name: The fermenter name

tempinf: Controls whether the device reports in Fahrenheit (true) or Celcius (false)


room: The offset applied to the room sensor

vessel: The offset applied to the vessel sensor


targeturl: The HTML endpoint which receives a JSON POST on schedule

freq: The frequency (in minutes) at which the application sends a status POST


bfkey: The hexadecimal key provided by Brewer’s Friend to allow POSTing data to your brew

freq: The frequency (in minutes) at which the application sends a status POST to Brewer’s Friend

Sets a semaphore indicating that the controller has reset one time after the firmware update
Sets a semaphore indicating that the controller has reset two times after firmware update and that SPIFFS update may begin
An indication that both firmware and SPIFFS OTA has completed

The following represents the different methods and messages used.

Outbound API

Triggers the controller to send all of its configuration items
Triggers the controller to send the last status payload
    "api_key":"Brew Bubbles",
    "device_source":"Brew Bubbles",
    "name":"Fermenter 1",
Returns the current controller firmware and SPIFFS version in JSON format:
    "version": "0.1.1"
Returns the currently available controller firmware and SPIFFS version from the Brew Bubbles website in the same format as the local version

Inbound API

The controller uses inbound web page access to configure and control Brew Bubbles.


The controller uses inbound endpoints to configure Brew Bubbles:

Processes a JSON POST to single configuration item only in the format shown above
Clears all update related semaphores
Allows the application of all configuration items in the format above in a single JSON POST


The following pages take action upon access:

Accessing this page resets all WiFi configuration items and reset the controller
Accessing this page begins the OTA update process

Downstream Targets

Downstream targets are systems to which Brew Bubbles sends data on a schedule. Sending data to various targets is done in similar yet specific formats.

Note that since the temperature probes are optional, they report as -100 in either temperature format when not connected. A sensor failure also results in this reading.

General HTTP Targets

General targets are targets that take an unqualified HTTP post. Currently, systems that are known to support Brew Bubbles are BrewPi Remix and Fermentrack.

Brew Bubbles makes the post with no authentication nor key, and in the following format:

    "api_key":"Brew Bubbles",
    "device_source":"Brew Bubbles",

Brewer’s Friend Target

Brew Bubbles natively and specifically supports posting data to Brewer’s Friend.

Brewer’s Friend requires an API key to either be sent in the header or as part of the URL. To help protect the integrity of the key from simple sniffing, Brew Bubbles puts the API key in the header as an X-AIO-Key.


    "api_key":"Brew Bubbles",
    "device_source":"Brew Bubbles",