From 18489afaff09d2ff36227da0da22e83e5c7ce4bc Mon Sep 17 00:00:00 2001 From: LBussy Date: Sat, 15 Apr 2023 11:57:37 -0500 Subject: [PATCH] Initial conversion to MyST --- docs/api/index.md | 991 ++++++++++++++++ docs/api/index.rst | 1035 ----------------- docs/conf.py | 12 +- docs/context/about/{index.rst => index.md} | 14 +- docs/context/about/license.md | 11 + docs/context/about/license.rst | 11 - docs/context/help/index.md | 17 + docs/context/help/index.rst | 17 - docs/context/home/{index.rst => index.md} | 20 +- docs/context/index.md | 29 + docs/context/index.rst | 29 - .../calibrate/{index.rst => index.md} | 43 +- .../advanced/reset/{index.rst => index.md} | 14 +- .../advanced/update/{index.rst => index.md} | 23 +- .../advanced/wifi/{index.rst => index.md} | 23 +- docs/context/settings/controller/index.md | 19 + docs/context/settings/controller/index.rst | 19 - .../settings/taps/{index.rst => index.md} | 19 +- .../settings/targets/kegscreen/index.md | 11 + .../settings/targets/kegscreen/index.rst | 11 - docs/context/settings/targets/rpints/index.md | 17 + .../context/settings/targets/rpints/index.rst | 17 - .../settings/targets/taplistio/index.md | 18 + .../settings/targets/taplistio/index.rst | 19 - .../targets/url/{index.rst => index.md} | 14 +- .../control/{index.rst => index.md} | 18 +- .../sensors/{index.rst => index.md} | 14 +- .../temperatures/{index.rst => index.md} | 16 +- docs/contributions/{index.rst => index.md} | 9 +- docs/firmware/index.md | 50 + docs/firmware/index.rst | 51 - docs/{index.rst => index.md} | 56 +- docs/networking/{index.rst => index.md} | 92 +- docs/operations/index.md | 52 + docs/operations/index.rst | 52 - docs/pcbassembly/{index.rst => index.md} | 84 +- docs/planning/{index.rst => index.md} | 76 +- docs/requirements.txt | 2 +- docs/sysassembly/{index.rst => index.md} | 40 +- docs/todo.md | 7 + docs/todo.rst | 6 - docs/troubleshooting/{index.rst => index.md} | 47 +- 42 files changed, 1529 insertions(+), 1596 deletions(-) create mode 100644 docs/api/index.md delete mode 100644 docs/api/index.rst rename docs/context/about/{index.rst => index.md} (64%) create mode 100644 docs/context/about/license.md delete mode 100644 docs/context/about/license.rst create mode 100644 docs/context/help/index.md delete mode 100644 docs/context/help/index.rst rename docs/context/home/{index.rst => index.md} (79%) create mode 100644 docs/context/index.md delete mode 100644 docs/context/index.rst rename docs/context/settings/advanced/calibrate/{index.rst => index.md} (82%) rename docs/context/settings/advanced/reset/{index.rst => index.md} (58%) rename docs/context/settings/advanced/update/{index.rst => index.md} (73%) rename docs/context/settings/advanced/wifi/{index.rst => index.md} (66%) create mode 100644 docs/context/settings/controller/index.md delete mode 100644 docs/context/settings/controller/index.rst rename docs/context/settings/taps/{index.rst => index.md} (75%) create mode 100644 docs/context/settings/targets/kegscreen/index.md delete mode 100644 docs/context/settings/targets/kegscreen/index.rst create mode 100644 docs/context/settings/targets/rpints/index.md delete mode 100644 docs/context/settings/targets/rpints/index.rst create mode 100644 docs/context/settings/targets/taplistio/index.md delete mode 100644 docs/context/settings/targets/taplistio/index.rst rename docs/context/settings/targets/url/{index.rst => index.md} (60%) rename docs/context/settings/temperature/control/{index.rst => index.md} (61%) rename docs/context/settings/temperature/sensors/{index.rst => index.md} (63%) rename docs/context/temperatures/{index.rst => index.md} (82%) rename docs/contributions/{index.rst => index.md} (75%) create mode 100644 docs/firmware/index.md delete mode 100644 docs/firmware/index.rst rename docs/{index.rst => index.md} (73%) rename docs/networking/{index.rst => index.md} (75%) create mode 100644 docs/operations/index.md delete mode 100644 docs/operations/index.rst rename docs/pcbassembly/{index.rst => index.md} (52%) rename docs/planning/{index.rst => index.md} (62%) rename docs/sysassembly/{index.rst => index.md} (89%) create mode 100644 docs/todo.md delete mode 100644 docs/todo.rst rename docs/troubleshooting/{index.rst => index.md} (55%) diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 00000000..9d92dc47 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,991 @@ +(api)= + +# Keg Cop API + +:::{note} +As of version 1.2.0, all PUT and action API usage must include an `X-KegCop-Secret` header with a value identical to the controller GUID. + +The secret may be obtained by querying the `/api/v1/info/secret` endpoint. + +This is obviously not intended to replace good security practices, and in no way would I ever recommend that you EVER expose this to the Internet or an unprotected network. +::: + +Keg Cop uses a combination of API types: + +- [Client-Initiated Communication] +- [Controller-Initiated Communication] + +## Client-Initiated Communication + +Client-initiated communication is initiated from a system other than the controller to retrieve data or initiate a data update or state change in the controller. This is broken down into: + +- [Action Page Handlers]: Pages that access will initiate a change or present a state. +- [Info Page Handlers]: Pages accessed to retrieve information about the controller's state and its systems. +- [Configuration Page Handlers]: Pages intended to provide a means by which the controller and application features and properties may be updated. + +### Action Page Handlers + +These action page handlers exist within the Action Page API tree: + +- [Ping] +- [WiFi Reset] +- [Controller Reset] +- [Online Update] +- [Clear Update State] +- [Set Calibration Mode] +- [Clear Calibration Mode] + +#### Ping + +- **Address:** {file}`/api/v1/ping/` +- **Valid Methods:** {file}`GET` +- **Data:** Ignored +- **Response:** {file}`200 Ok` +- **Description:** While not an action per se, this page provides a simple response intended to semaphore the existence of the controller. +- **Error Message:** None + +#### WiFi Reset + +- **Address:** {file}`/api/v1/action/wifireset/` +- **Valid Methods:** {file}`PUT` +- **Data:** Ignored +- **Response:** {file}`200 Ok` +- **Description:** This endpoint will initiate both erasure of the saved WiFi credentials and a controller restart. As the restart will be without credentials, this will cause the controller to start a captive portal for configuration. +- **Error Message:** Any method other than {file}`PUT` will result in a {file}`405 Method Not Allowed` error. + +#### Controller Reset + +- **Address:** {file}`/api/v1/action/reset/` +- **Valid Methods:** {file}`PUT` +- **Data:** Ignored +- **Response:** {file}`200 Ok` +- **Description:** This endpoint will initiate a controller restart with no loss of data. +- **Error Message:** Any method other than {file}`PUT` will result in a {file}`405 Method Not Allowed` error. + +#### Online Update + +- **Address:** {file}`/api/v1/action/updatestart/` +- **Valid Methods:** {file}`PUT` +- **Data:** Ignored +- **Response:** {file}`200 Ok` +- **Description:** This endpoint will initiate a controller upgrade attempt using the firmware avaialble at the author's website. Both firmware and filesystem updates will be attempted. The controller will restart several times during this process. +- **Error Message:** Any method other than {file}`PUT` will result in a {file}`405 Method Not Allowed` error. + +#### Clear Update State + +- **Address:** {file}`/api/v1/action/clearupdate/` +- **Valid Methods:** {file}`PUT` +- **Data:** Ignored +- **Response:** {file}`200 Ok` +- **Description:** This endpoint will clear the update semaphores which trigger an update attempt initiated on a controller restart. +- **Error Message:** Any method other than {file}`PUT` will result in a {file}`405 Method Not Allowed` error. + +#### Set Calibration Mode + +- **Address:** {file}`/api/v1/action/setcalmode/` +- **Valid Methods:** {file}`PUT` +- **Data:** Ignored +- **Response:** {file}`200 Ok` +- **Description:** This endpoint will put the controller in calibration mode. This mode pauses pour calculations in order to allow a user to measure a pour and calculate pulses per unit. The pulses accumulated will debit upon completion. +- **Error Message:** Any method other than {file}`PUT` will result in a {file}`405 Method Not Allowed` error. + +#### Clear Calibration Mode + +- **Address:** {file}`/api/v1/action/clearcalmode/` +- **Valid Methods:** {file}`PUT` +- **Data:** Ignored +- **Response:** {file}`200 Ok` +- **Description:** This endpoint will clear the calibration mode, and debit any accumulated pulses. +- **Error Message:** Any method other than {file}`PUT` will result in a {file}`405 Method Not Allowed` error. + +### Info Page Handlers + +These information provider pages exist within the Info API tree: + +- [Reset Reason] +- [Heap Information] +- [Uptime] +- [This Version] +- [That Version] +- [Pulses] +- [Sensors] +- [Reset Reason] +- [Heap Information] +- [Uptime] +- [This Version] +- [That Version] +- [Pulses] +- [Sensors] +- [Secret] + +#### Reset Reason + +- **Address:** {file}`/api/v1/info/resetreason/` +- **Valid Methods:** {file}`ANY` +- **Data:** Ignored +- **Description:** Reason for the most reset controller reset. +- **Error Message:** None. +- **Response:** + +```json +{ + "r": { + "reason": "ESP_RST_POWERON", + "description": "Reset due to power-on event" + } +} +``` + +Where: + +- `reason` = Any of the [resetReason] enums listed in [resetreasons.cpp]. +- `description` = Any of the [resetDescription] enums listed in [resetreasons.cpp]. + +#### Heap Information + +- **Address:** {file}`/api/v1/info/heap/` +- **Valid Methods:** {file}`ANY` +- **Data:** Ignored +- **Description:** Current information about the controller's heap memory. +- **Error Message:** None. +- **Response:** + +```json +{ + "h": { + "free": 224092, + "max": 48256, + "frag": 79 + } +} +``` + +Where: + +- `free` = Total free bytes in the heap +- `max` = Size of largest free block in the heap +- `frag` = Approximate fragmentation of the heap + +#### Uptime + +- **Address:** {file}`/api/v1/info/uptime/` +- **Valid Methods:** {file}`ANY` +- **Data:** Ignored +- **Description:** Elapsed time since last controller reset. +- **Error Message:** None. +- **Response:** + +```json +{ + "u": { + "days": 0, + "hours": 1, + "minutes": 8, + "seconds": 38, + "millis": 246 + } +} +``` + +#### This Version + +- **Address:** {file}`/api/v1/info/thisVersion/` +- **Valid Methods:** {file}`ANY` +- **Data:** Ignored +- **Description:** Currently installed application information. +- **Error Message:** None. +- **Response:** + +```json +{ + "fw_version": "0.0.1", + "fs_version": "0.0.1", + "branch": "update_versions", + "build": "d5713a3" +} +``` + +Where: + +- `fw_version` = Current firmware version (tag from Git when built) +- `fs_version` = Current filesystem version (tag from Git when built) +- `branch` = Current Git branch +- `build` = Short hash of current Git commit + +#### That Version + +- **Address:** {file}`/api/v1/info/thatVersion/` +- **Valid Methods:** {file}`ANY` +- **Data:** Ignored +- **Description:** Version of application available for upgrade. +- **Error Message:** None. +- **Response:** + +```json +{ + "fw_version": "0.0.1", + "fs_version": "0.0.1" +} +``` + +Where: + +- `fw_version` = Available firmware version (tag from Git when built) +- `fs_version` = Available filesystem version (tag from Git when built) + +#### Pulses + +- **Address:** {file}`/api/v1/info/pulses/` +- **Valid Methods:** {file}`ANY` +- **Data:** Ignored +- **Description:** An array representing the current pulse count per flowmeter during calibration. +- **Error Message:** None. +- **Response:** + +```json +{ + "pulses": [ + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0 + ] +} +``` + +#### Sensors + +- **Address:** {file}`/api/v1/info/sensors/` +- **Valid Methods:** {file}`ANY` +- **Data:** Ignored +- **Description:** Information pertaining to temperature sensors and control. +- **Error Message:** None. +- **Response:** + +```json +{ + "imperial": true, + "controlpoint": 4, + "setting": 35, + "status": 6, + "controlenabled": true, + "sensors": [ + { + "enable": true, + "name": "Room", + "value": -196.6 + }, + { + "enable": true, + "name": "Tower", + "value": -196.6 + }, + { + "enable": true, + "name": "Upper Chamber", + "value": -196.6 + }, + { + "enable": true, + "name": "Lower Chamber", + "value": -196.6 + }, + { + "enable": true, + "name": "Keg", + "value": -196.6 + } + ], + "displayenabled": true +} +``` + +Where: + +- `imperial` = True for imperial units, false for metric. +- `controlpoint` = Zero-based index representing the current [sensor] by which temperature is being controlled. +- `setting` = Temperature setting in current units. +- `status` = Zero based index representing the current temperature control [state]. +- `controlenabled` = Boolean for enabling temperature control. +- `tfansetpoint` = Temperature setting for tower fan in current units. +- `tfanstate` = Zero based index representing the current tower temperature control [state]. +- `tfancontrolenabled` = Boolean for enabling tower temperature control. +- `sensors` = An array of temperature sensors denoting the `name`, `enable` status, and current `value` of each. +- `displayenabled` = Boolean to display temperatures on the web UI or not. + +#### Sensors + +- **Address:** {file}`/api/v1/info/secret/` +- **Valid Methods:** {file}`ANY` +- **Data:** Ignored +- **Description:** Secret used for PUT operations. +- **Error Message:** None. +- **Response:** + +```json +{ + "secret": "5C95AB340000D8A7" +} +``` + +Where: + +- `secret` = Hexidecimal string for representing controller GUID. + +### Configuration Page Handlers + +The configuration page API tree allows retrieval of current states or setting condition and properties via the same endpoint. Available pages are: + +- [Settings] +- [Taps] +- [Theme] + +#### Settings + +Both `GET` and `PUT` are valid methods for this endpoint. + +##### GET + +- **Address:** {file}`/api/v1/config/settings/` +- **Valid Methods:** {file}`GET` +- **Data:** Ignored +- **Description:** The {file}`GET` method for this endpoint will return the current endpoint configuration. +- **Error Message:** Any method other than {file}`PUT` or {file}`GET` will result in a {file}`405 Method Not Allowed` error. +- **Response:** + +```json +{ + "apconfig": { + "ssid": "kegcop", + "passphrase": "kegcop21" + }, + "copconfig": { + "guid": "952DE6B40000A1A6", + "hostname": "kegcop", + "nodrd": false, + "breweryname": "Silver Fox Brewery", + "kegeratorname": "Keezer", + "controlnum": 0, + "serial": false, + "imperial": true, + "tapsolenoid": true + }, + "ota": { + "dospiffs1": false, + "dospiffs2": false, + "didupdate": false + }, + "temps": { + "setpoint": 35, + "controlpoint": 4, + "controlenabled": true, + "tfancontrolenabled": true, + "tfansetpoint": 38.5, + "tfanonhigh": false, + "roomenabled": true, + "roomcal": 1, + "towerenabled": true, + "towercal": 2, + "upperenabled": true, + "uppercal": -1, + "lowerenabled": true, + "lowercal": -2, + "kegenabled": true, + "kegcal": 3 + }, + "kegscreen": { + "url": "http://mule.local/kegcop/", + "update": false + }, + "rpintstarget": { + "host": "mule.local", + "port": 1883, + "username": "", + "password": "", + "topic": "kegcop", + "update": false + }, + "taplistio": { + "venue": "taplist-12345", + "secret":"secret-abcdefghijk", + "lastsent":1656966278, + "update":false + }, + "urltarget": { + "url": "http://mule.local", + "freq": 30, + "update": false + } +} +``` + +##### PUT + +- **Address:** {file}`/api/v1/config/settings/` +- **Valid Methods:** {file}`PUT` +- **Response:** `200 Ok` on success, `500 Unable to process data` on failure. +- **Description:** The {file}`PUT` method for this endpoint will allow endpoint configuration. +- **Error Message:** Any method other than {file}`PUT` or {file}`GET` will result in a {file}`405 Method Not Allowed` error. +- **Data:** + +The PUT should follow standard form submission data format, with the following items available. Items not listed are not available for change. Some names are not the same as they appear in the JSON; the PUT format is flattened but represented below in groups by the JSON stanza. + +###### copconfig + +- `guid` - Not configurable via settings, this is a calculated/derived value unique to the controller. +- `hostname` - A string representing a valid hostname (without the .local portion) between 3 and 32 characters. +- `breweryname` - A string representing the brewery name, used to logically group multiple controllers and display the web page. +- `kegeratorname` - A string representing the kegerator name, used to identify the controller and displayed within the web page display. +- `controlnum` - A 1-based index of the controller sequence. This should be unique in the brewery and will help identify the same tapid across multiple controllers. +- `imperial` - A boolean representing imperial versus metric units to be used by the controller. Changing this value will result in a conversion of all stored values to the target units. Multiple toggles could result in accrued rounding errors and some loss of accuracy. +- `tapsolenoid` - A simple control point intended to control a local solenoid by an upstream system or the web UI. + +###### temps + +- `setpoint` - The temperature setpoint in the configured units to which the system will cool the cabinet. This is a floating-point number. +- `controlpoint` - A zero-based index indicating the [sensor] by which the system will be cooled. +- `controlenabled` - A boolean turning temperature control on and off. +- `tfansetpoint` = The temperature setpoint for cooling in the configured units to which the system will cool the tower. This is a floating-point number. +- `tfanstate` = Zero based index representing the current tower temperature control [state]. +- `tfancontrolenabled` = Boolean for enabling tower temperature control. +- `enableroom` - Enable the room sensor to be displayed. +- `roomcal` - A signed floating-point number by which the room sensor will be calibrated. +- `enabletower` - Enable the tower sensor to be displayed. +- `towercal` - A signed floating-point number by which the tower sensor will be calibrated. +- `enableupper` - Enable the uppercal sensor to be displayed. +- `uppercal` - A signed floating-point number by which the upper sensor will be calibrated. +- `enablelower` - Enable the lower sensor to be displayed. +- `lowercal` - A signed floating-point number by which the lower sensor will be calibrated. +- `enablekeg` - Enable the keg sensor to be displayed. +- `kegcal` - A signed floating-point number by which the keg sensor will be calibrated. + +###### kegscreen (url) + +- `kegscreen` - The full URL target for the KegScreen system. + +###### rpintstarget + +- `rpintshost` - The fully-qualified domain name for the Raspberry Pints system's MQTT broker. +- `rpintsport` - The target MQTT port. +- `rpintsusername` - The MQTT user name, blank if not used. +- `rpintspassword` - The MQTT password, blank if not used. +- `rpintstopic` - The MQTT topic. + +###### taplistio + +- `venue` - The taplist.io venue name. +- `secret` - The taplist.io API secret key. +- `lastsent` - Time (epoch) the report was last sent. Used for rate limiting. +- `update` - Whether there is a Taplist.io update pending. + +###### urltarget + +- `targeturl` - The full URL target for the generic URL target. +- `targetfreq` - The frequency at which data will be pushed. + +#### Taps + +Both `GET` and `PUT` are valid methods for this endpoint. + +##### GET + +- **Address:** {file}`/api/v1/config/taps/` +- **Valid Methods:** {file}`GET` +- **Data:** Ignored +- **Description:** The {file}`GET` method for this endpoint will return the current endpoint configuration. +- **Error Message:** Any method other than `PUT` or `GET` will result in a `405 Method Not Allowed` error. +- **Response:** + +```json +{ + "imperial": true, + "taps": [ + { + "tapid": 0, + "label": 1, + "taplistioTap": 1, + "pin": 4, + "ppu": 21120, + "name": "Pudswiller Doors", + "capacity": 5, + "remaining": 4.2, + "active": true, + "calibrating": false + }, + { + "tapid": 1, + "label": 2, + "taplistioTap": 0, + "pin": 16, + "ppu": 21120, + "name": "Bug's House Ale", + "capacity": 5, + "remaining": 3.3, + "active": true, + "calibrating": false + }, + { + "tapid": 2, + "label": 3, + "taplistioTap": 0, + "pin": 17, + "ppu": 21120, + "name": "Navelgazer IPA", + "capacity": 5, + "remaining": 1.5, + "active": true, + "calibrating": false + }, + { + "tapid": 3, + "label": 4, + "taplistioTap": 0, + "pin": 18, + "ppu": 21120, + "name": "Tanked 7", + "capacity": 5, + "remaining": 2.2, + "active": true, + "calibrating": false + }, + { + "tapid": 4, + "label": 5, + "taplistioTap": 0, + "pin": 19, + "ppu": 21120, + "name": "Ringaling Lager", + "capacity": 15.5, + "remaining": 13.1, + "active": true, + "calibrating": false + }, + { + "tapid": 5, + "label": 6, + "taplistioTap": 0, + "pin": 21, + "ppu": 21120, + "name": "Peter Skee", + "capacity": 5, + "remaining": 4.1, + "active": true, + "calibrating": false + }, + { + "tapid": 6, + "label": 7, + "taplistioTap": 0, + "pin": 22, + "ppu": 21120, + "name": "Undead Guy", + "capacity": 5, + "remaining": 3.9, + "active": true, + "calibrating": false + }, + { + "tapid": 7, + "label": 8, + "taplistioTap": 0, + "pin": 23, + "ppu": 21120, + "name": "Who's Garden", + "capacity": 5, + "remaining": 1.2, + "active": true, + "calibrating": false + }, + { + "tapid": 8, + "label": 9, + "taplistioTap": 0, + "pin": 13, + "ppu": 21120, + "name": "Mystery Mead", + "capacity": 5, + "remaining": 3.7, + "active": true, + "calibrating": false + } + ] +} +``` + +Where: + +- `imperial` = True for imperial units, false for metric. +- `taps` = An array with information for each of the taps configured. + +Tap information follows the following format: + +- `tapid` = The zero-based index representing the tap number internally. +- `label` = The one-based label representing the tap number externally. +- `taplistioTap` = The one-based label representing the Taplist.io tap number externally. +- `pin` = The microcontroller [pin] defined for the tap. +- `ppu` = The pulses per configured flow unit. +- `name` = The name of the beverage currently on tap. +- `capacity` = The capacity, in current units, of the attached keg. +- `remaining` = The amount remaining, in current units, of the attached keg. +- `active` = Denotes whether the tap is active (displayed) or not. +- `calibrating` = Switch to put the tap in calibration mode. + +##### PUT + +- **Address:** {file}`/api/v1/config/taps/` +- **Valid Methods:** {file}`PUT` +- **Response:** `200 Ok` on success, `500 Unable to process data` on failure. +- **Description:** The {file}`PUT` method for this endpoint will allow endpoint configuration. +- **Error Message:** Any method other than {file}`PUT` or {file}`GET` will result in a `405 Method Not Allowed` error. +- **Data:** + +The PUT should follow standard form submission data format, with the following items available. Items not listed are not available for change. Some names are not the same as they appear in the JSON; the PUT format is flattened but represented below in groups by the JSON stanza. + +`imperial` = True for imperial units, false for metric. +`taps` = An array with information for each of the taps configured. + +The tap array follows the following format for each of the nine available taps: + +- `tap` = The zero-based index representing the tap number. +- `label` = The one-based label representing the tap number externally. +- `ppu` = The pulses per configured flow unit. +- `bevname` = The name of the beverage currently on tap. +- `cap` = The capacity, in floating-point current units, of the attached keg. +- `remain` = The amount remaining, in floating-point current units, of the attached keg. +- `active` = Denotes whether the tap is active (displayed) or not. + +#### Theme + +Both `GET` and `PUT` are valid methods for this endpoint. + +##### GET + +- **Address:** {file}`/api/v1/config/theme/` +- **Valid Methods:** {file}`GET` +- **Data:** Ignored +- **Description:** The {file}`GET` method for this endpoint will return the current theme configuration. +- **Error Message:** Any method other than `PUT` or `GET` will result in a `405 Method Not Allowed` error. +- **Response:** + +```json +{ +"theme": "cerulean" +} +``` + +Where: + +- `theme` = Any pre-configured Bootstrap-compliant theme + +##### PUT + +- **Address:** {file}`/api/v1/config/theme/` +- **Valid Methods:** {file}`PUT` +- **Response:** `200 Ok` on success, `500 Unable to process data` on failure. +- **Description:** The {file}`PUT` method for this endpoint will allow endpoint configuration. +- **Error Message:** Any method other than {file}`PUT` or {file}`GET` will result in a `405 Method Not Allowed` error. +- **Data:** + +The PUT should follow standard form submission data format, with the following item available. + +- `theme` = Any pre-configured Bootstrap-compliant theme + +## Controller-Initiated Communication + +These reports are sent, when so configured, via WiFi to upstream systems. + +- [KegScreen] +- [URL] +- [Raspberry Pints] + +### KegScreen + +Keg Cop sends five different reports to the upstream KegScreen system: + +- [Send Tap Information Report] +- [Send Pulse Report] +- [Send Kick Report] +- [Send Cooling State Report] +- [Send Temperature Report] + +#### Send Tap Information Report + +This report is sent to the upstream system whenever a change is made to any tap information. The configuration is as follows: + +```json +{ + "api":"Keg Cop", + "guid": "952DE6B40000A1A6", + "hostname":"kegcop", + "breweryname":"Silver Fox Brewery", + "kegeratorname":"Keezer", + "reporttype":"tapinfo", + "imperial":1, + "tapid":3, + "name":"Tanked 7", + "ppu":21118, + "remaining":2.2, + "capacity":5, + "active":true, + "calibrating":false +} +``` + +#### Send Pulse Report + +Whenever a pour completes, Keg Cop sends a pour report to the KegScreen system. The format is as follows: + +```json +{ + "api":"Keg Cop", + "guid": "952DE6B40000A1A6", + "hostname":"kegcop", + "breweryname":"Silver Fox Brewery", + "kegeratorname":"Keezer", + "reporttype":"pourreport", + "tapid":0, + "imperial":true, + "dispensed":0.004451, + "remaining":4.195549 +} +``` + +#### Send Kick Report + +Keg Cop employs an algorithm for detecting a kicked keg. When the pour volume exceeds a predetermined amount per second, Keg Cop considers that as evidence the keg is blowing foam and will mark the keg inactive. A kick report will be sent to the KegScreen system. The format is as follows: + +```json +{ + "api":"Keg Cop", + "guid": "952DE6B40000A1A6", + "hostname":"kegcop", + "breweryname":"Silver Fox Brewery", + "kegeratorname":"Keezer", + "reporttype":"kickreport", + "tapid":0 +} +``` + +#### Send Cooling State Report + +Whenever the cooling state changes, a state report is triggered for the KegScreen system. The format is as follows: + +```json +{ + "api":"Keg Cop", + "guid": "952DE6B40000A1A6", + "hostname":"kegcop", + "breweryname":"Silver Fox Brewery", + "kegeratorname":"Keezer", + "reporttype":"coolstate", + "state":3, + "tfancontrolenabled": true, + "tfansetpoint": 38.5, + "tfanonhigh": false +} +``` + +Where: + +- `API` = Intended to be an indicator to the upstream system for the source of information. +- `guid` = A unique identifier for the controller, used to help differentiate between multiple Keg Cops. +- `hostname` = Current mDNS hostname. +- `brewername` = A name used to group several Keg Cops logically. +- `reporttype` = The type of information to be found in this report. +- `state` = A zero-based index representing the current temperature control [state] +- `tfansetpoint` = Temperature setting for tower fan in current units. +- `tfanstate` = Zero based index representing the current tower temperature control [state]. +- `tfancontrolenabled` = Boolean for enabling tower temperature control. + +#### Send Temperature Report + +A report containing all temperature points is sent to the KegScreen system every minute. The format is as follows: + +```json +{ + "api":"Keg Cop", + "guid": "952DE6B40000A1A6", + "hostname":"kegcop", + "breweryname":"Silver Fox Brewery", + "kegeratorname":"Keezer", + "reporttype":"tempreport", + "imperial":true, + "controlpoint":4, + "setting":35, + "status":3, + "controlenabled":true, + "tfancontrolenabled": true, + "tfansetpoint": 38.5, + "tfanonhigh": false, + "sensors":[ + { + "name":"Room", + "value":85.1, + "enabled":true + }, + { + "name":"Tower", + "value":85.1, + "enabled":true + }, + { + "name":"Upper Chamber", + "value":78.8, + "enabled":true + }, + { + "name":"Lower Chamber", + "value":75.2, + "enabled":true + }, + { + "name":"Keg", + "value":84.2, + "enabled":true + } + ] +} +``` + +### URL + +The Target URL Report provides a holistic picture of the system to a custom/third-party endpoint. It is a timer-based POST; a change of state does not trigger it. As with all target system configurations within Keg Cop, it will post to HTTP only. The format is as follows: + +```json +{ + "api":"Keg Cop", + "guid": "952DE6B40000A1A6", + "hostname":"kegcop", + "breweryname":"Silver Fox Brewery", + "kegeratorname":"Keezer", + "reporttype":"targeturlreport", + "imperial":true, + "controlpoint":4, + "setting":35, + "status":2, + "controlenabled":true, + "tfancontrolenabled": true, + "tfansetpoint": 38.5, + "tfanonhigh": false, + "sensors":[ + { + "name":"Room", + "value":84.1982, + "enabled":true + }, + { + "name":"Tower", + "value":84.1964, + "enabled":true + }, + { + "name":"Upper Chamber", + "value":77.0018, + "enabled":true + }, + { + "name":"Lower Chamber", + "value":73.6286, + "enabled":true + }, + { + "name":"Keg", + "value":83.2946, + "enabled":true + } + ], + "taps":[ + { + "tapid":0, + "ppu":21118, + "name":"Pudswiller Doors", + "capacity":5, + "remaining":4.1955, + "active":false + }, + { + "tapid":1, + "ppu":21118, + "name":"Bug's House Ale", + "capacity":5, + "remaining":3.299195, + "active":true + }, + { + "tapid":2, + "ppu":21118, + "name":"Navelgazer IPA", + "capacity":5, + "remaining":1.499148, + "active":true + }, + { + "tapid":3, + "ppu":21118, + "name":"Tanked 7", + "capacity":5, + "remaining":2.197301, + "active":true + }, + { + "tapid":4, + "ppu":21118, + "name":"Ringaling Lager", + "capacity":15.5, + "remaining":13.09872, + "active":true + }, + { + "tapid":5, + "ppu":21118, + "name":"Peter Skee", + "capacity":5, + "remaining":4.1, + "active":true + }, + { + "tapid":6, + "ppu":21118, + "name":"Undead Guy", + "capacity":5, + "remaining":3.899053, + "active":true + }, + { + "tapid":7, + "ppu":21118, + "name":"Who's Garden", + "capacity":5, + "remaining":1.2, + "active":true + } + ] +} +``` + +### Raspberry Pints + +Keg Cop will send a message via MQTT to a configured endpoint. Raspberry Pints does not leverage standard MQTT format; this format is specific to Raspberry Pints. The format is as follows: + +``` +P;-1;0;737 +``` + +Where: + +- `P` = A pulse report (the only one currently supported via MQTT by Raspberry Pints.) +- `-1` = The user. Since Keg Cop does not support user IDs, a -1 is sent to indicate "no user." +- `0` = Tap number. +- `737` = Number of raw pulses to report. + +[pin]: https://github.com/lbussy/keg-cop/blob/d5713a3323ff9998a7986f801d07a92093c0c3f8/src/config.h#L615-L703 +[resetdescription]: https://github.com/lbussy/keg-cop/blob/d5713a3323ff9998a7986f801d07a92093c0c3f8/src/resetreasons.cpp#L41-L53 +[resetreason]: https://github.com/lbussy/keg-cop/blob/d5713a3323ff9998a7986f801d07a92093c0c3f8/src/resetreasons.cpp#L27-L39 +[resetreasons.cpp]: https://github.com/lbussy/keg-cop/blob/main/src/resetreasons.cpp#L1 +[sensor]: https://github.com/lbussy/keg-cop/blob/d5713a3323ff9998a7986f801d07a92093c0c3f8/src/tempsensors.cpp#L25 +[state]: https://github.com/lbussy/keg-cop/blob/d5713a3323ff9998a7986f801d07a92093c0c3f8/src/thermostat.h#L31-L41 diff --git a/docs/api/index.rst b/docs/api/index.rst deleted file mode 100644 index 9b0aa4ba..00000000 --- a/docs/api/index.rst +++ /dev/null @@ -1,1035 +0,0 @@ -.. _api: - -Keg Cop API -################ - -.. note:: - As of version 1.2.0, all PUT and action API usage must include an ``X-KegCop-Secret`` header with a value identical to the controller GUID. - - The secret may be obtained by querying the ``/api/v1/info/secret`` endpoint. - - This is obviously not intended to replace good security practices, and in no way would I ever recommend that you EVER expose this to the Internet or an unprotected network. - -Keg Cop uses a combination of API types: - -- `Client-Initiated Communication`_ -- `Controller-Initiated Communication`_ - -Client-Initiated Communication -******************************** - -Client-initiated communication is initiated from a system other than the controller to retrieve data or initiate a data update or state change in the controller. This is broken down into: - -- `Action Page Handlers`_: Pages that access will initiate a change or present a state. -- `Info Page Handlers`_: Pages accessed to retrieve information about the controller's state and its systems. -- `Configuration Page Handlers`_: Pages intended to provide a means by which the controller and application features and properties may be updated. - -Action Page Handlers -====================== - -These action page handlers exist within the Action Page API tree: - -- `Ping`_ -- `WiFi Reset`_ -- `Controller Reset`_ -- `Online Update`_ -- `Clear Update State`_ -- `Set Calibration Mode`_ -- `Clear Calibration Mode`_ - -Ping -------- - -- **Address:** :file:`/api/v1/ping/` -- **Valid Methods:** :file:`GET` -- **Data:** Ignored -- **Response:** :file:`200 Ok` -- **Description:** While not an action per se, this page provides a simple response intended to semaphore the existence of the controller. -- **Error Message:** None - -WiFi Reset ------------ - -- **Address:** :file:`/api/v1/action/wifireset/` -- **Valid Methods:** :file:`PUT` -- **Data:** Ignored -- **Response:** :file:`200 Ok` -- **Description:** This endpoint will initiate both erasure of the saved WiFi credentials and a controller restart. As the restart will be without credentials, this will cause the controller to start a captive portal for configuration. -- **Error Message:** Any method other than :file:`PUT` will result in a :file:`405 Method Not Allowed` error. - -Controller Reset ------------------- - -- **Address:** :file:`/api/v1/action/reset/` -- **Valid Methods:** :file:`PUT` -- **Data:** Ignored -- **Response:** :file:`200 Ok` -- **Description:** This endpoint will initiate a controller restart with no loss of data. -- **Error Message:** Any method other than :file:`PUT` will result in a :file:`405 Method Not Allowed` error. - -Online Update ------------------ - -- **Address:** :file:`/api/v1/action/updatestart/` -- **Valid Methods:** :file:`PUT` -- **Data:** Ignored -- **Response:** :file:`200 Ok` -- **Description:** This endpoint will initiate a controller upgrade attempt using the firmware avaialble at the author's website. Both firmware and filesystem updates will be attempted. The controller will restart several times during this process. -- **Error Message:** Any method other than :file:`PUT` will result in a :file:`405 Method Not Allowed` error. - -Clear Update State --------------------- - -- **Address:** :file:`/api/v1/action/clearupdate/` -- **Valid Methods:** :file:`PUT` -- **Data:** Ignored -- **Response:** :file:`200 Ok` -- **Description:** This endpoint will clear the update semaphores which trigger an update attempt initiated on a controller restart. -- **Error Message:** Any method other than :file:`PUT` will result in a :file:`405 Method Not Allowed` error. - -Set Calibration Mode ----------------------- - -- **Address:** :file:`/api/v1/action/setcalmode/` -- **Valid Methods:** :file:`PUT` -- **Data:** Ignored -- **Response:** :file:`200 Ok` -- **Description:** This endpoint will put the controller in calibration mode. This mode pauses pour calculations in order to allow a user to measure a pour and calculate pulses per unit. The pulses accumulated will debit upon completion. -- **Error Message:** Any method other than :file:`PUT` will result in a :file:`405 Method Not Allowed` error. - -Clear Calibration Mode --------------------------- - -- **Address:** :file:`/api/v1/action/clearcalmode/` -- **Valid Methods:** :file:`PUT` -- **Data:** Ignored -- **Response:** :file:`200 Ok` -- **Description:** This endpoint will clear the calibration mode, and debit any accumulated pulses. -- **Error Message:** Any method other than :file:`PUT` will result in a :file:`405 Method Not Allowed` error. - -Info Page Handlers -====================== - -These information provider pages exist within the Info API tree: - -- `Reset Reason`_ -- `Heap Information`_ -- `Uptime`_ -- `This Version`_ -- `That Version`_ -- `Pulses`_ -- `Sensors`_ -- `Reset Reason`_ -- `Heap Information`_ -- `Uptime`_ -- `This Version`_ -- `That Version`_ -- `Pulses`_ -- `Sensors`_ -- `Secret`_ - -Reset Reason --------------- - -- **Address:** :file:`/api/v1/info/resetreason/` -- **Valid Methods:** :file:`ANY` -- **Data:** Ignored -- **Description:** Reason for the most reset controller reset. -- **Error Message:** None. -- **Response:** - -.. code-block:: json - - { - "r": { - "reason": "ESP_RST_POWERON", - "description": "Reset due to power-on event" - } - } - -Where: - -- ``reason`` = Any of the resetReason_ enums listed in resetreasons.cpp_. -- ``description`` = Any of the resetDescription_ enums listed in resetreasons.cpp_. - -Heap Information ---------------------- - -- **Address:** :file:`/api/v1/info/heap/` -- **Valid Methods:** :file:`ANY` -- **Data:** Ignored -- **Description:** Current information about the controller's heap memory. -- **Error Message:** None. -- **Response:** - -.. code-block:: json - - { - "h": { - "free": 224092, - "max": 48256, - "frag": 79 - } - } - -Where: - -- ``free`` = Total free bytes in the heap -- ``max`` = Size of largest free block in the heap -- ``frag`` = Approximate fragmentation of the heap - -Uptime ------------ - -- **Address:** :file:`/api/v1/info/uptime/` -- **Valid Methods:** :file:`ANY` -- **Data:** Ignored -- **Description:** Elapsed time since last controller reset. -- **Error Message:** None. -- **Response:** - -.. code-block:: json - - { - "u": { - "days": 0, - "hours": 1, - "minutes": 8, - "seconds": 38, - "millis": 246 - } - } - -This Version ----------------- - -- **Address:** :file:`/api/v1/info/thisVersion/` -- **Valid Methods:** :file:`ANY` -- **Data:** Ignored -- **Description:** Currently installed application information. -- **Error Message:** None. -- **Response:** - -.. code-block:: json - - { - "fw_version": "0.0.1", - "fs_version": "0.0.1", - "branch": "update_versions", - "build": "d5713a3" - } - -Where: - -- ``fw_version`` = Current firmware version (tag from Git when built) -- ``fs_version`` = Current filesystem version (tag from Git when built) -- ``branch`` = Current Git branch -- ``build`` = Short hash of current Git commit - -That Version ---------------- - -- **Address:** :file:`/api/v1/info/thatVersion/` -- **Valid Methods:** :file:`ANY` -- **Data:** Ignored -- **Description:** Version of application available for upgrade. -- **Error Message:** None. -- **Response:** - -.. code-block:: json - - { - "fw_version": "0.0.1", - "fs_version": "0.0.1" - } - -Where: - -- ``fw_version`` = Available firmware version (tag from Git when built) -- ``fs_version`` = Available filesystem version (tag from Git when built) - -Pulses -------------- - -- **Address:** :file:`/api/v1/info/pulses/` -- **Valid Methods:** :file:`ANY` -- **Data:** Ignored -- **Description:** An array representing the current pulse count per flowmeter during calibration. -- **Error Message:** None. -- **Response:** - -.. code-block:: json - - { - "pulses": [ - 0, - 0, - 0, - 0, - 0, - 0, - 0, - 0, - 0 - ] - } - -Sensors --------------- - -- **Address:** :file:`/api/v1/info/sensors/` -- **Valid Methods:** :file:`ANY` -- **Data:** Ignored -- **Description:** Information pertaining to temperature sensors and control. -- **Error Message:** None. -- **Response:** - -.. code-block:: json - - { - "imperial": true, - "controlpoint": 4, - "setting": 35, - "status": 6, - "controlenabled": true, - "sensors": [ - { - "enable": true, - "name": "Room", - "value": -196.6 - }, - { - "enable": true, - "name": "Tower", - "value": -196.6 - }, - { - "enable": true, - "name": "Upper Chamber", - "value": -196.6 - }, - { - "enable": true, - "name": "Lower Chamber", - "value": -196.6 - }, - { - "enable": true, - "name": "Keg", - "value": -196.6 - } - ], - "displayenabled": true - } - -Where: - -- ``imperial`` = True for imperial units, false for metric. -- ``controlpoint`` = Zero-based index representing the current sensor_ by which temperature is being controlled. -- ``setting`` = Temperature setting in current units. -- ``status`` = Zero based index representing the current temperature control state_. -- ``controlenabled`` = Boolean for enabling temperature control. -- ``tfansetpoint`` = Temperature setting for tower fan in current units. -- ``tfanstate`` = Zero based index representing the current tower temperature control state_. -- ``tfancontrolenabled`` = Boolean for enabling tower temperature control. -- ``sensors`` = An array of temperature sensors denoting the ``name``, ``enable`` status, and current ``value`` of each. -- ``displayenabled`` = Boolean to display temperatures on the web UI or not. - -Sensors --------------- - -- **Address:** :file:`/api/v1/info/secret/` -- **Valid Methods:** :file:`ANY` -- **Data:** Ignored -- **Description:** Secret used for PUT operations. -- **Error Message:** None. -- **Response:** - -.. code-block:: json - - { - "secret": "5C95AB340000D8A7" - } - -Where: - -- ``secret`` = Hexidecimal string for representing controller GUID. - -Configuration Page Handlers -================================= - -The configuration page API tree allows retrieval of current states or setting condition and properties via the same endpoint. Available pages are: - -- `Settings`_ -- `Taps`_ -- `Theme`_ - -Settings ------------------- - -Both ``GET`` and ``PUT`` are valid methods for this endpoint. - -GET -^^^^^^^^ - -- **Address:** :file:`/api/v1/config/settings/` -- **Valid Methods:** :file:`GET` -- **Data:** Ignored -- **Description:** The :file:`GET` method for this endpoint will return the current endpoint configuration. -- **Error Message:** Any method other than :file:`PUT` or :file:`GET` will result in a :file:`405 Method Not Allowed` error. -- **Response:** - -.. code-block:: json - - { - "apconfig": { - "ssid": "kegcop", - "passphrase": "kegcop21" - }, - "copconfig": { - "guid": "952DE6B40000A1A6", - "hostname": "kegcop", - "nodrd": false, - "breweryname": "Silver Fox Brewery", - "kegeratorname": "Keezer", - "controlnum": 0, - "serial": false, - "imperial": true, - "tapsolenoid": true - }, - "ota": { - "dospiffs1": false, - "dospiffs2": false, - "didupdate": false - }, - "temps": { - "setpoint": 35, - "controlpoint": 4, - "controlenabled": true, - "tfancontrolenabled": true, - "tfansetpoint": 38.5, - "tfanonhigh": false, - "roomenabled": true, - "roomcal": 1, - "towerenabled": true, - "towercal": 2, - "upperenabled": true, - "uppercal": -1, - "lowerenabled": true, - "lowercal": -2, - "kegenabled": true, - "kegcal": 3 - }, - "kegscreen": { - "url": "http://mule.local/kegcop/", - "update": false - }, - "rpintstarget": { - "host": "mule.local", - "port": 1883, - "username": "", - "password": "", - "topic": "kegcop", - "update": false - }, - "taplistio": { - "venue": "taplist-12345", - "secret":"secret-abcdefghijk", - "lastsent":1656966278, - "update":false - }, - "urltarget": { - "url": "http://mule.local", - "freq": 30, - "update": false - } - } - -PUT -^^^^^^^^ - -- **Address:** :file:`/api/v1/config/settings/` -- **Valid Methods:** :file:`PUT` -- **Response:** ``200 Ok`` on success, ``500 Unable to process data`` on failure. -- **Description:** The :file:`PUT` method for this endpoint will allow endpoint configuration. -- **Error Message:** Any method other than :file:`PUT` or :file:`GET` will result in a :file:`405 Method Not Allowed` error. -- **Data:** - -The PUT should follow standard form submission data format, with the following items available. Items not listed are not available for change. Some names are not the same as they appear in the JSON; the PUT format is flattened but represented below in groups by the JSON stanza. - -copconfig -""""""""""" - -- ``guid`` - Not configurable via settings, this is a calculated/derived value unique to the controller. -- ``hostname`` - A string representing a valid hostname (without the .local portion) between 3 and 32 characters. -- ``breweryname`` - A string representing the brewery name, used to logically group multiple controllers and display the web page. -- ``kegeratorname`` - A string representing the kegerator name, used to identify the controller and displayed within the web page display. -- ``controlnum`` - A 1-based index of the controller sequence. This should be unique in the brewery and will help identify the same tapid across multiple controllers. -- ``imperial`` - A boolean representing imperial versus metric units to be used by the controller. Changing this value will result in a conversion of all stored values to the target units. Multiple toggles could result in accrued rounding errors and some loss of accuracy. -- ``tapsolenoid`` - A simple control point intended to control a local solenoid by an upstream system or the web UI. - -temps -""""""""" - -- ``setpoint`` - The temperature setpoint in the configured units to which the system will cool the cabinet. This is a floating-point number. -- ``controlpoint`` - A zero-based index indicating the sensor_ by which the system will be cooled. -- ``controlenabled`` - A boolean turning temperature control on and off. -- ``tfansetpoint`` = The temperature setpoint for cooling in the configured units to which the system will cool the tower. This is a floating-point number. -- ``tfanstate`` = Zero based index representing the current tower temperature control state_. -- ``tfancontrolenabled`` = Boolean for enabling tower temperature control. -- ``enableroom`` - Enable the room sensor to be displayed. -- ``roomcal`` - A signed floating-point number by which the room sensor will be calibrated. -- ``enabletower`` - Enable the tower sensor to be displayed. -- ``towercal`` - A signed floating-point number by which the tower sensor will be calibrated. -- ``enableupper`` - Enable the uppercal sensor to be displayed. -- ``uppercal`` - A signed floating-point number by which the upper sensor will be calibrated. -- ``enablelower`` - Enable the lower sensor to be displayed. -- ``lowercal`` - A signed floating-point number by which the lower sensor will be calibrated. -- ``enablekeg`` - Enable the keg sensor to be displayed. -- ``kegcal`` - A signed floating-point number by which the keg sensor will be calibrated. - -kegscreen (url) -""""""""""""""" - -- ``kegscreen`` - The full URL target for the KegScreen system. - -rpintstarget -"""""""""""""" - -- ``rpintshost`` - The fully-qualified domain name for the Raspberry Pints system's MQTT broker. -- ``rpintsport`` - The target MQTT port. -- ``rpintsusername`` - The MQTT user name, blank if not used. -- ``rpintspassword`` - The MQTT password, blank if not used. -- ``rpintstopic`` - The MQTT topic. - -taplistio -"""""""""""""" - -- ``venue`` - The taplist.io venue name. -- ``secret`` - The taplist.io API secret key. -- ``lastsent`` - Time (epoch) the report was last sent. Used for rate limiting. -- ``update`` - Whether there is a Taplist.io update pending. - -urltarget -""""""""""" - -- ``targeturl`` - The full URL target for the generic URL target. -- ``targetfreq`` - The frequency at which data will be pushed. - -Taps --------------- - -Both ``GET`` and ``PUT`` are valid methods for this endpoint. - -GET -^^^^^^^^ - -- **Address:** :file:`/api/v1/config/taps/` -- **Valid Methods:** :file:`GET` -- **Data:** Ignored -- **Description:** The :file:`GET` method for this endpoint will return the current endpoint configuration. -- **Error Message:** Any method other than ``PUT`` or ``GET`` will result in a ``405 Method Not Allowed`` error. -- **Response:** - -.. code-block:: json - - { - "imperial": true, - "taps": [ - { - "tapid": 0, - "label": 1, - "taplistioTap": 1, - "pin": 4, - "ppu": 21120, - "name": "Pudswiller Doors", - "capacity": 5, - "remaining": 4.2, - "active": true, - "calibrating": false - }, - { - "tapid": 1, - "label": 2, - "taplistioTap": 0, - "pin": 16, - "ppu": 21120, - "name": "Bug's House Ale", - "capacity": 5, - "remaining": 3.3, - "active": true, - "calibrating": false - }, - { - "tapid": 2, - "label": 3, - "taplistioTap": 0, - "pin": 17, - "ppu": 21120, - "name": "Navelgazer IPA", - "capacity": 5, - "remaining": 1.5, - "active": true, - "calibrating": false - }, - { - "tapid": 3, - "label": 4, - "taplistioTap": 0, - "pin": 18, - "ppu": 21120, - "name": "Tanked 7", - "capacity": 5, - "remaining": 2.2, - "active": true, - "calibrating": false - }, - { - "tapid": 4, - "label": 5, - "taplistioTap": 0, - "pin": 19, - "ppu": 21120, - "name": "Ringaling Lager", - "capacity": 15.5, - "remaining": 13.1, - "active": true, - "calibrating": false - }, - { - "tapid": 5, - "label": 6, - "taplistioTap": 0, - "pin": 21, - "ppu": 21120, - "name": "Peter Skee", - "capacity": 5, - "remaining": 4.1, - "active": true, - "calibrating": false - }, - { - "tapid": 6, - "label": 7, - "taplistioTap": 0, - "pin": 22, - "ppu": 21120, - "name": "Undead Guy", - "capacity": 5, - "remaining": 3.9, - "active": true, - "calibrating": false - }, - { - "tapid": 7, - "label": 8, - "taplistioTap": 0, - "pin": 23, - "ppu": 21120, - "name": "Who's Garden", - "capacity": 5, - "remaining": 1.2, - "active": true, - "calibrating": false - }, - { - "tapid": 8, - "label": 9, - "taplistioTap": 0, - "pin": 13, - "ppu": 21120, - "name": "Mystery Mead", - "capacity": 5, - "remaining": 3.7, - "active": true, - "calibrating": false - } - ] - } - -Where: - -- ``imperial`` = True for imperial units, false for metric. -- ``taps`` = An array with information for each of the taps configured. - -Tap information follows the following format: - -- ``tapid`` = The zero-based index representing the tap number internally. -- ``label`` = The one-based label representing the tap number externally. -- ``taplistioTap`` = The one-based label representing the Taplist.io tap number externally. -- ``pin`` = The microcontroller pin_ defined for the tap. -- ``ppu`` = The pulses per configured flow unit. -- ``name`` = The name of the beverage currently on tap. -- ``capacity`` = The capacity, in current units, of the attached keg. -- ``remaining`` = The amount remaining, in current units, of the attached keg. -- ``active`` = Denotes whether the tap is active (displayed) or not. -- ``calibrating`` = Switch to put the tap in calibration mode. - -PUT -^^^^^^^ - -- **Address:** :file:`/api/v1/config/taps/` -- **Valid Methods:** :file:`PUT` -- **Response:** ``200 Ok`` on success, ``500 Unable to process data`` on failure. -- **Description:** The :file:`PUT` method for this endpoint will allow endpoint configuration. -- **Error Message:** Any method other than :file:`PUT` or :file:`GET` will result in a `405 Method Not Allowed` error. -- **Data:** - -The PUT should follow standard form submission data format, with the following items available. Items not listed are not available for change. Some names are not the same as they appear in the JSON; the PUT format is flattened but represented below in groups by the JSON stanza. - -``imperial`` = True for imperial units, false for metric. -``taps`` = An array with information for each of the taps configured. - -The tap array follows the following format for each of the nine available taps: - -- ``tap`` = The zero-based index representing the tap number. -- ``label`` = The one-based label representing the tap number externally. -- ``ppu`` = The pulses per configured flow unit. -- ``bevname`` = The name of the beverage currently on tap. -- ``cap`` = The capacity, in floating-point current units, of the attached keg. -- ``remain`` = The amount remaining, in floating-point current units, of the attached keg. -- ``active`` = Denotes whether the tap is active (displayed) or not. - -Theme --------------- - -Both ``GET`` and ``PUT`` are valid methods for this endpoint. - -GET -^^^^^^^^ - -- **Address:** :file:`/api/v1/config/theme/` -- **Valid Methods:** :file:`GET` -- **Data:** Ignored -- **Description:** The :file:`GET` method for this endpoint will return the current theme configuration. -- **Error Message:** Any method other than ``PUT`` or ``GET`` will result in a ``405 Method Not Allowed`` error. -- **Response:** - -.. code-block:: json - - { - "theme": "cerulean" - } - -Where: - -- ``theme`` = Any pre-configured Bootstrap-compliant theme - -PUT -^^^^^^^ - -- **Address:** :file:`/api/v1/config/theme/` -- **Valid Methods:** :file:`PUT` -- **Response:** ``200 Ok`` on success, ``500 Unable to process data`` on failure. -- **Description:** The :file:`PUT` method for this endpoint will allow endpoint configuration. -- **Error Message:** Any method other than :file:`PUT` or :file:`GET` will result in a `405 Method Not Allowed` error. -- **Data:** - -The PUT should follow standard form submission data format, with the following item available. - -- ``theme`` = Any pre-configured Bootstrap-compliant theme - -Controller-Initiated Communication -*************************************** - -These reports are sent, when so configured, via WiFi to upstream systems. - -- `KegScreen`_ -- `URL`_ -- `Raspberry Pints`_ - -KegScreen -============= - -Keg Cop sends five different reports to the upstream KegScreen system: - -- `Send Tap Information Report`_ -- `Send Pulse Report`_ -- `Send Kick Report`_ -- `Send Cooling State Report`_ -- `Send Temperature Report`_ - -Send Tap Information Report ------------------------------ - -This report is sent to the upstream system whenever a change is made to any tap information. The configuration is as follows: - -.. code-block:: json - - { - "api":"Keg Cop", - "guid": "952DE6B40000A1A6", - "hostname":"kegcop", - "breweryname":"Silver Fox Brewery", - "kegeratorname":"Keezer", - "reporttype":"tapinfo", - "imperial":1, - "tapid":3, - "name":"Tanked 7", - "ppu":21118, - "remaining":2.2, - "capacity":5, - "active":true, - "calibrating":false - } - -Send Pulse Report --------------------- - -Whenever a pour completes, Keg Cop sends a pour report to the KegScreen system. The format is as follows: - -.. code-block:: json - - { - "api":"Keg Cop", - "guid": "952DE6B40000A1A6", - "hostname":"kegcop", - "breweryname":"Silver Fox Brewery", - "kegeratorname":"Keezer", - "reporttype":"pourreport", - "tapid":0, - "imperial":true, - "dispensed":0.004451, - "remaining":4.195549 - } - -Send Kick Report ------------------- - -Keg Cop employs an algorithm for detecting a kicked keg. When the pour volume exceeds a predetermined amount per second, Keg Cop considers that as evidence the keg is blowing foam and will mark the keg inactive. A kick report will be sent to the KegScreen system. The format is as follows: - -.. code-block:: json - - { - "api":"Keg Cop", - "guid": "952DE6B40000A1A6", - "hostname":"kegcop", - "breweryname":"Silver Fox Brewery", - "kegeratorname":"Keezer", - "reporttype":"kickreport", - "tapid":0 - } - -Send Cooling State Report ------------------------------- - -Whenever the cooling state changes, a state report is triggered for the KegScreen system. The format is as follows: - -.. code-block:: json - - { - "api":"Keg Cop", - "guid": "952DE6B40000A1A6", - "hostname":"kegcop", - "breweryname":"Silver Fox Brewery", - "kegeratorname":"Keezer", - "reporttype":"coolstate", - "state":3, - "tfancontrolenabled": true, - "tfansetpoint": 38.5, - "tfanonhigh": false - } - -Where: - -- ``API`` = Intended to be an indicator to the upstream system for the source of information. -- ``guid`` = A unique identifier for the controller, used to help differentiate between multiple Keg Cops. -- ``hostname`` = Current mDNS hostname. -- ``brewername`` = A name used to group several Keg Cops logically. -- ``reporttype`` = The type of information to be found in this report. -- ``state`` = A zero-based index representing the current temperature control state_ -- ``tfansetpoint`` = Temperature setting for tower fan in current units. -- ``tfanstate`` = Zero based index representing the current tower temperature control state_. -- ``tfancontrolenabled`` = Boolean for enabling tower temperature control. - -Send Temperature Report ------------------------------- - -A report containing all temperature points is sent to the KegScreen system every minute. The format is as follows: - -.. code-block:: json - - { - "api":"Keg Cop", - "guid": "952DE6B40000A1A6", - "hostname":"kegcop", - "breweryname":"Silver Fox Brewery", - "kegeratorname":"Keezer", - "reporttype":"tempreport", - "imperial":true, - "controlpoint":4, - "setting":35, - "status":3, - "controlenabled":true, - "tfancontrolenabled": true, - "tfansetpoint": 38.5, - "tfanonhigh": false, - "sensors":[ - { - "name":"Room", - "value":85.1, - "enabled":true - }, - { - "name":"Tower", - "value":85.1, - "enabled":true - }, - { - "name":"Upper Chamber", - "value":78.8, - "enabled":true - }, - { - "name":"Lower Chamber", - "value":75.2, - "enabled":true - }, - { - "name":"Keg", - "value":84.2, - "enabled":true - } - ] - } - -URL -================ - -The Target URL Report provides a holistic picture of the system to a custom/third-party endpoint. It is a timer-based POST; a change of state does not trigger it. As with all target system configurations within Keg Cop, it will post to HTTP only. The format is as follows: - -.. code-block:: json - - { - "api":"Keg Cop", - "guid": "952DE6B40000A1A6", - "hostname":"kegcop", - "breweryname":"Silver Fox Brewery", - "kegeratorname":"Keezer", - "reporttype":"targeturlreport", - "imperial":true, - "controlpoint":4, - "setting":35, - "status":2, - "controlenabled":true, - "tfancontrolenabled": true, - "tfansetpoint": 38.5, - "tfanonhigh": false, - "sensors":[ - { - "name":"Room", - "value":84.1982, - "enabled":true - }, - { - "name":"Tower", - "value":84.1964, - "enabled":true - }, - { - "name":"Upper Chamber", - "value":77.0018, - "enabled":true - }, - { - "name":"Lower Chamber", - "value":73.6286, - "enabled":true - }, - { - "name":"Keg", - "value":83.2946, - "enabled":true - } - ], - "taps":[ - { - "tapid":0, - "ppu":21118, - "name":"Pudswiller Doors", - "capacity":5, - "remaining":4.1955, - "active":false - }, - { - "tapid":1, - "ppu":21118, - "name":"Bug's House Ale", - "capacity":5, - "remaining":3.299195, - "active":true - }, - { - "tapid":2, - "ppu":21118, - "name":"Navelgazer IPA", - "capacity":5, - "remaining":1.499148, - "active":true - }, - { - "tapid":3, - "ppu":21118, - "name":"Tanked 7", - "capacity":5, - "remaining":2.197301, - "active":true - }, - { - "tapid":4, - "ppu":21118, - "name":"Ringaling Lager", - "capacity":15.5, - "remaining":13.09872, - "active":true - }, - { - "tapid":5, - "ppu":21118, - "name":"Peter Skee", - "capacity":5, - "remaining":4.1, - "active":true - }, - { - "tapid":6, - "ppu":21118, - "name":"Undead Guy", - "capacity":5, - "remaining":3.899053, - "active":true - }, - { - "tapid":7, - "ppu":21118, - "name":"Who's Garden", - "capacity":5, - "remaining":1.2, - "active":true - } - ] - } - -Raspberry Pints -======================== - -Keg Cop will send a message via MQTT to a configured endpoint. Raspberry Pints does not leverage standard MQTT format; this format is specific to Raspberry Pints. The format is as follows: - -.. code-block:: - - P;-1;0;737 - -Where: - -- ``P`` = A pulse report (the only one currently supported via MQTT by Raspberry Pints.) -- ``-1`` = The user. Since Keg Cop does not support user IDs, a -1 is sent to indicate "no user." -- ``0`` = Tap number. -- ``737`` = Number of raw pulses to report. - - -.. _resetreasons.cpp: https://github.com/lbussy/keg-cop/blob/main/src/resetreasons.cpp#L1 -.. _resetReason: https://github.com/lbussy/keg-cop/blob/d5713a3323ff9998a7986f801d07a92093c0c3f8/src/resetreasons.cpp#L27-L39 -.. _resetDescription: https://github.com/lbussy/keg-cop/blob/d5713a3323ff9998a7986f801d07a92093c0c3f8/src/resetreasons.cpp#L41-L53 -.. _sensor: https://github.com/lbussy/keg-cop/blob/d5713a3323ff9998a7986f801d07a92093c0c3f8/src/tempsensors.cpp#L25 -.. _state: https://github.com/lbussy/keg-cop/blob/d5713a3323ff9998a7986f801d07a92093c0c3f8/src/thermostat.h#L31-L41 -.. _pin: https://github.com/lbussy/keg-cop/blob/d5713a3323ff9998a7986f801d07a92093c0c3f8/src/config.h#L615-L703 diff --git a/docs/conf.py b/docs/conf.py index 15bac590..68c18b65 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,14 +14,6 @@ import sys #sys.path.insert(0, os.path.abspath('.')) import subprocess -import recommonmark - -# for MarkdownParser -from recommonmark.transform import AutoStructify -from sphinx_markdown_parser.parser import MarkdownParser - -# At top on conf.py (with other import statements) -from sphinx_markdown_parser.transform import AutoStructify import sphinx_bootstrap_theme from sphinx.ext import todo @@ -49,7 +41,7 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['recommonmark', 'sphinx.ext.todo'] +extensions = ['myst_parser', 'sphinx.ext.todo'] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -60,7 +52,7 @@ # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = '.md' # The master toctree document. master_doc = 'index' diff --git a/docs/context/about/index.rst b/docs/context/about/index.md similarity index 64% rename from docs/context/about/index.rst rename to docs/context/about/index.md index 9a4095c2..d9aad872 100644 --- a/docs/context/about/index.rst +++ b/docs/context/about/index.md @@ -1,11 +1,11 @@ -.. _about: +(about)= -About Keg Cop -############### +# About Keg Cop The About page shows the currently installed version in the header. Additionally, it contains links to the main website, the license under which I have released Keg Cop, and a link to my profile on Homebrewtalk. -.. image:: about.png - :scale: 25% - :align: center - :alt: About Keg Cop +```{image} about.png +:align: center +:alt: About Keg Cop +:scale: 25% +``` diff --git a/docs/context/about/license.md b/docs/context/about/license.md new file mode 100644 index 00000000..21c81f7b --- /dev/null +++ b/docs/context/about/license.md @@ -0,0 +1,11 @@ +(license)= + +# Keg Cop License + +I have released Keg Cop under the [MIT License](https://github.com/lbussy/keg-cop/blob/master/LICENSE). + +```{image} license.png +:align: center +:alt: Keg Cop License +:scale: 50% +``` diff --git a/docs/context/about/license.rst b/docs/context/about/license.rst deleted file mode 100644 index 32e3ce30..00000000 --- a/docs/context/about/license.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _license: - -Keg Cop License -############### - -I have released Keg Cop under the `MIT License `_. - -.. image:: license.png - :scale: 50% - :align: center - :alt: Keg Cop License diff --git a/docs/context/help/index.md b/docs/context/help/index.md new file mode 100644 index 00000000..9d7309fa --- /dev/null +++ b/docs/context/help/index.md @@ -0,0 +1,17 @@ +(help)= + +# Help Links + +The Help page displays important support links for Keg Cop: + +```{image} help.png +:align: center +:alt: Help Links +:scale: 50% +``` + +- [Visit the Homepage](https://www.kegcop.com): A link to the Keg Cop main website. +- [Visit project on GitHub](https://github.com/lbussys/keg-cop): A link to the GitHub repository. +- [Read the Documentation](https://docs.kegcop.com): A link to this documentation. +- [Report an issue or bug](https://github.com/lbussy/keg-cop/issues): A link to the Issues list within the GitHub repository. Use this for real issues or bugs; for support or questions, use the next link. +- [Get support or chat with other users on the HomebrewTalk Thread](https://support.kegcop.com): A link to the main thread on HomebrewTalk where general discussions and "how do I?" conversations should be posted. diff --git a/docs/context/help/index.rst b/docs/context/help/index.rst deleted file mode 100644 index 9095ae22..00000000 --- a/docs/context/help/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _help: - -Help Links -################ - -The Help page displays important support links for Keg Cop: - -.. image:: help.png - :scale: 50% - :align: center - :alt: Help Links - -- `Visit the Homepage `_: A link to the Keg Cop main website. -- `Visit project on GitHub `_: A link to the GitHub repository. -- `Read the Documentation `_: A link to this documentation. -- `Report an issue or bug `_: A link to the Issues list within the GitHub repository. Use this for real issues or bugs; for support or questions, use the next link. -- `Get support or chat with other users on the HomebrewTalk Thread `_: A link to the main thread on HomebrewTalk where general discussions and "how do I?" conversations should be posted. diff --git a/docs/context/home/index.rst b/docs/context/home/index.md similarity index 79% rename from docs/context/home/index.rst rename to docs/context/home/index.md index 07128644..92a7ad12 100644 --- a/docs/context/home/index.rst +++ b/docs/context/home/index.md @@ -1,18 +1,20 @@ -.. _home: +(home)= +```{eval-rst} .. include:: +``` -Home Page -############## +# Home Page -.. image:: home.png - :scale: 50% - :align: center - :alt: Home Page +```{image} home.png +:align: center +:alt: Home Page +:scale: 50% +``` -The Keg Cop home page is displayed when you first connect via your chosen web browser. You will see a main menu across the top border if you connect with a standard desktop web browser. If in a mobile or portrait mode browser window, the list displays when you click the hamburger bar (|equiv|) in the top-right corner. +The Keg Cop home page is displayed when you first connect via your chosen web browser. You will see a main menu across the top border if you connect with a standard desktop web browser. If in a mobile or portrait mode browser window, the list displays when you click the hamburger bar ({{ equiv }}) in the top-right corner. -In the top-left side of the main container is a title concatenated from the :ref:`kegerator ` and :ref:`brewery name ` (e.g. "Main Kegerator in Silver Fox Brewery.") +In the top-left side of the main container is a title concatenated from the {ref}`kegerator ` and {ref}`brewery name ` (e.g. "Main Kegerator in Silver Fox Brewery.") On the right side of this container is the current control point temperature if used. The block around the temperature indicates the temperature control status. You may also hover over this section for a tooltip explaining the state. diff --git a/docs/context/index.md b/docs/context/index.md new file mode 100644 index 00000000..a597ee3e --- /dev/null +++ b/docs/context/index.md @@ -0,0 +1,29 @@ +(context)= + +# Context Help + +The following are links to context help for the web pages controlling the Keg Cop application. Generally these are accessed via a hotlink in the web UI. + +```{toctree} +:glob: true +:maxdepth: 1 +:titlesonly: true + +home/index +temperatures/index +settings/controller/index +settings/taps/index +settings/temperature/control/index +settings/temperature/sensors/index +settings/targets/kegscreen/index +settings/targets/url/index +settings/targets/rpints/index +settings/targets/taplistio/index +settings/advanced/calibrate/index +settings/advanced/reset/index +settings/advanced/update/index +settings/advanced/wifi/index +help/index +about/index +about/license +``` diff --git a/docs/context/index.rst b/docs/context/index.rst deleted file mode 100644 index 1d0ab573..00000000 --- a/docs/context/index.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _context: - -Context Help -################## - -The following are links to context help for the web pages controlling the Keg Cop application. Generally these are accessed via a hotlink in the web UI. - -.. toctree:: - :maxdepth: 1 - :titlesonly: - :glob: - - home/index - temperatures/index - settings/controller/index - settings/taps/index - settings/temperature/control/index - settings/temperature/sensors/index - settings/targets/kegscreen/index - settings/targets/url/index - settings/targets/rpints/index - settings/targets/taplistio/index - settings/advanced/calibrate/index - settings/advanced/reset/index - settings/advanced/update/index - settings/advanced/wifi/index - help/index - about/index - about/license diff --git a/docs/context/settings/advanced/calibrate/index.rst b/docs/context/settings/advanced/calibrate/index.md similarity index 82% rename from docs/context/settings/advanced/calibrate/index.rst rename to docs/context/settings/advanced/calibrate/index.md index 1a85897e..3b600bc1 100644 --- a/docs/context/settings/advanced/calibrate/index.rst +++ b/docs/context/settings/advanced/calibrate/index.md @@ -1,24 +1,24 @@ -.. _calibrate: +(calibrate)= -Calibrate Flowmeters -###################### +# Calibrate Flowmeters -.. image:: calibrate.png - :scale: 50% - :align: center - :alt: Flowmeter Calibration Screen +```{image} calibrate.png +:align: center +:alt: Flowmeter Calibration Screen +:scale: 50% +``` Upon opening the Calibrate Flowmeters page, you are presented with a dropdown to select the flowmeter to be calibrated. After choosing the meter, select a radio button to select between calibrating by a weight or a volume measurement. The Choose Mode button will activate upon selecting a method. Pressing this button will open an additional dialog, depending upon your choice. Calibration by volume is often less accurate than weight; however, using volume is the most straightforward method. -Calibration by Volume -********************** +## Calibration by Volume -.. image:: volume.png - :scale: 50% - :align: center - :alt: Calibration by Volume Screen +```{image} volume.png +:align: center +:alt: Calibration by Volume Screen +:scale: 50% +``` Calibration by volume involves measuring a tap pull of a beverage and then recording that measurement. A larger pour will be more accurate than a smaller one. Enter volume measurements in the units for which you have configured Keg Cop. Use milliliters if using metric, or ounces if using imperial measurements. @@ -26,13 +26,13 @@ As you draw a beverage during calibration, the Pulses field will update with the When you are satisfied, use the Set PPG/PPL button to lock in the calibration. If you wish to reset the calculation back to its default, use the Reset button instead of saving. The pulses collected will be debited according to the new rate if you save, or the previously configured rate if you reset. -Calibration by Weight -********************** +## Calibration by Weight -.. image:: weight.png - :scale: 50% - :align: center - :alt: Calibration by Weight Screen +```{image} weight.png +:align: center +:alt: Calibration by Weight Screen +:scale: 50% +``` Since some beverages may have a specific gravity other than 1.000, and we measure by volume, adjustment of the measure taking into account the SG is possible. If you are unsure of what to use, 1.015 is a good middle of the road number for most homebrewed beer. If you leave it blank, the calibration employs 1.000 (water equivalence). @@ -42,7 +42,6 @@ As you draw a beverage during calibration, the Pulses field will update with the When you are satisfied, use the Set PPG/PPL button to lock in the calibration. If you wish to reset the calculation back to its default, use the Reset button instead of saving. The pulses collected will be debited according to the new rate if you save, or the previously configured rate if you reset. -Tap Setup -********************* +## Tap Setup -See the :ref:`Taps ` settings page for other tap settings. +See the {ref}`Taps ` settings page for other tap settings. diff --git a/docs/context/settings/advanced/reset/index.rst b/docs/context/settings/advanced/reset/index.md similarity index 58% rename from docs/context/settings/advanced/reset/index.rst rename to docs/context/settings/advanced/reset/index.md index 9b9f5553..1ba9b25e 100644 --- a/docs/context/settings/advanced/reset/index.rst +++ b/docs/context/settings/advanced/reset/index.md @@ -1,11 +1,11 @@ -.. _reset: +(reset)= -Reset Controller -################ +# Reset Controller -.. image:: reset.png - :scale: 50% - :align: center - :alt: Reset Controller +```{image} reset.png +:align: center +:alt: Reset Controller +:scale: 50% +``` Clicking the "Reset Controller" button in this UI will perform the same function as pressing the reset button on the controller. The controller will retain all settings. diff --git a/docs/context/settings/advanced/update/index.rst b/docs/context/settings/advanced/update/index.md similarity index 73% rename from docs/context/settings/advanced/update/index.rst rename to docs/context/settings/advanced/update/index.md index 6dc78986..501e1ea3 100644 --- a/docs/context/settings/advanced/update/index.rst +++ b/docs/context/settings/advanced/update/index.md @@ -1,20 +1,21 @@ -.. _update: +(update)= -Update Controller -######################## +# Update Controller -.. image:: update.png - :scale: 21% - :align: center - :alt: Check Versions +```{image} update.png +:align: center +:alt: Check Versions +:scale: 21% +``` This page will display the currently installed version as well as any available version og the firmware and filesystem. In almost every case, teh versions of firmware and filesystem should match. If they are different, it may be an indication of a failed updat. Pressing the "Update Firmware" button on this page will queue an update of the system application and website. The system will retain your configuration settings during the process. -.. image:: in-progress.png - :scale: 50% - :align: center - :alt: Do Update +```{image} in-progress.png +:align: center +:alt: Do Update +:scale: 50% +``` The process will take five or more minutes, depending upon your network configuration. When complete, the page will refresh to the home page. diff --git a/docs/context/settings/advanced/wifi/index.rst b/docs/context/settings/advanced/wifi/index.md similarity index 66% rename from docs/context/settings/advanced/wifi/index.rst rename to docs/context/settings/advanced/wifi/index.md index 0541d794..5c0426d6 100644 --- a/docs/context/settings/advanced/wifi/index.rst +++ b/docs/context/settings/advanced/wifi/index.md @@ -1,18 +1,19 @@ -.. _resetwifi: +(resetwifi)= -Reset WiFi -############## +# Reset WiFi -.. image:: wifi.png - :scale: 50% - :align: center - :alt: Reset WiFi +```{image} wifi.png +:align: center +:alt: Reset WiFi +:scale: 50% +``` If you plan to move your Keg Cop to a new location or connect to a new network, resetting the network settings ahead of time is a good idea. Pressing the "Reset WiFi" button is an irreversible action and will delete the current WiFi configuration. -.. image:: done.png - :scale: 50% - :align: center - :alt: WiFi Reset +```{image} done.png +:align: center +:alt: WiFi Reset +:scale: 50% +``` After this action, you will need to reconnect to the *kegcop* access point to reconfigure the WiFi settings. diff --git a/docs/context/settings/controller/index.md b/docs/context/settings/controller/index.md new file mode 100644 index 00000000..d683dddf --- /dev/null +++ b/docs/context/settings/controller/index.md @@ -0,0 +1,19 @@ +(controller)= + +# Controller Settings + +```{image} controller.png +:align: center +:alt: Controller Settings +:scale: 50% +``` + +The Controller Settings page allows configuration of settings which control the top-level settings of the system: + +- **Host Name**: This is the network hostname, to which you will connect as *\{hostname}*.local. Do not include the .local portion; the mDNS system will append this automatically. This name must be unique on the network, or unexpected behavior may result. Most computer systems and mobile devices support mDNS. For more information, please see the {ref}`mDNS FAQ `. +- **Brewery Name**: This is displayed on the {ref}`main page `. It concatenates with the Kegerator name, e.g., "*Taplist for Kegerator in Silver Fox Brewery.*" +- **Kegerator Name**: This displays on the main page. It concatenates with the Brewery name, e.g., e.g., "*Taplist for Kegerator in Silver Fox Brewery.*" This name reports to any upstream system. +- **Units**: + : - **Metric**: Volume reports in liters and milliliters, the temperature in degrees Celcius, and you will enter the flowmeter calibration in pulses per liter. + - **Imperial**: Volume reports in gallons and ounces, the temperature in degrees Fahrenheit, you will enter the flowmeter calibration in pulses per gallon. +- **Solenoid Relay**: This will energize or de-energize a relay. This setting controls a solenoid or bank of solenoids to turn the beverage flow on or off. I have provided this point for convenience; I intend for an upstream system to control it. diff --git a/docs/context/settings/controller/index.rst b/docs/context/settings/controller/index.rst deleted file mode 100644 index a541a11f..00000000 --- a/docs/context/settings/controller/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _controller: - -Controller Settings -###################### - -.. image:: controller.png - :scale: 50% - :align: center - :alt: Controller Settings - -The Controller Settings page allows configuration of settings which control the top-level settings of the system: - -- **Host Name**: This is the network hostname, to which you will connect as *{hostname}*.local. Do not include the .local portion; the mDNS system will append this automatically. This name must be unique on the network, or unexpected behavior may result. Most computer systems and mobile devices support mDNS. For more information, please see the :ref:`mDNS FAQ `. -- **Brewery Name**: This is displayed on the :ref:`main page `. It concatenates with the Kegerator name, e.g., "*Taplist for Kegerator in Silver Fox Brewery.*" -- **Kegerator Name**: This displays on the main page. It concatenates with the Brewery name, e.g., e.g., "*Taplist for Kegerator in Silver Fox Brewery.*" This name reports to any upstream system. -- **Units**: - - **Metric**: Volume reports in liters and milliliters, the temperature in degrees Celcius, and you will enter the flowmeter calibration in pulses per liter. - - **Imperial**: Volume reports in gallons and ounces, the temperature in degrees Fahrenheit, you will enter the flowmeter calibration in pulses per gallon. -- **Solenoid Relay**: This will energize or de-energize a relay. This setting controls a solenoid or bank of solenoids to turn the beverage flow on or off. I have provided this point for convenience; I intend for an upstream system to control it. diff --git a/docs/context/settings/taps/index.rst b/docs/context/settings/taps/index.md similarity index 75% rename from docs/context/settings/taps/index.rst rename to docs/context/settings/taps/index.md index 57222ebd..14b1e612 100644 --- a/docs/context/settings/taps/index.rst +++ b/docs/context/settings/taps/index.md @@ -1,20 +1,19 @@ -.. _taps: +(taps)= -Tap Settings -############## +# Tap Settings The first choice on the Settings screen is a drop-down tab labeled Taps. Clicking on this will allow you to configure taps number one through nine individually. -.. image:: tap.png - :scale: 50% - :align: center - :alt: Tap UI +```{image} tap.png +:align: center +:alt: Tap UI +:scale: 50% +``` Enter the pulses per gallon/liter, the name of the beverage on tap, and the keg's capacity. You may enter the initial amount remaining in the keg when you tap it or adjust it as needed. The amount remaining will debit automatically during use. Setting the keg as active/inactive will determine if the keg reports to the upstream system and if it displays on the home page. The keg will be set to inactive automatically when a kick event is detected. -PPG/PPL Calibration -********************* +## PPG/PPL Calibration -See the :ref:`flowmeter calibration ` page for more information on calculating the PPG/PPL. +See the {ref}`flowmeter calibration ` page for more information on calculating the PPG/PPL. diff --git a/docs/context/settings/targets/kegscreen/index.md b/docs/context/settings/targets/kegscreen/index.md new file mode 100644 index 00000000..b70cfd94 --- /dev/null +++ b/docs/context/settings/targets/kegscreen/index.md @@ -0,0 +1,11 @@ +(kegscreen)= + +# KegScreen Target + +```{image} kegscreen.png +:align: center +:alt: KegScreen Settings +:scale: 50% +``` + +The KegScreen page allows you to set or clear the URL of the KegScreen endpoint. Removing the value will disable KegScreen reports. diff --git a/docs/context/settings/targets/kegscreen/index.rst b/docs/context/settings/targets/kegscreen/index.rst deleted file mode 100644 index 4c774abc..00000000 --- a/docs/context/settings/targets/kegscreen/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _kegscreen: - -KegScreen Target -################### - -.. image:: kegscreen.png - :scale: 50% - :align: center - :alt: KegScreen Settings - -The KegScreen page allows you to set or clear the URL of the KegScreen endpoint. Removing the value will disable KegScreen reports. diff --git a/docs/context/settings/targets/rpints/index.md b/docs/context/settings/targets/rpints/index.md new file mode 100644 index 00000000..b3342722 --- /dev/null +++ b/docs/context/settings/targets/rpints/index.md @@ -0,0 +1,17 @@ +(rpints)= + +# Raspberry Pints Target + +```{image} rpints.png +:align: center +:alt: Raspberry Pints Settings +:scale: 25% +``` + +The Raspberry Pints page allows you to forward pours to an MQTT-enabled Raspberry Pints installation. The settings are as follows: + +- *Broker Address:* \[Required\] Enter the fully-qualified domain name of the Raspberry Pints target. You may use \*.local addresses, IP addresses, or Internet-facing addresses. +- *Broker Port:* \[Required\] The port to use, the default MQTT port is 1883. +- *User Name:* \[Optional\] If required by the MQTT broker, this is the user name by which you will be authenticated. Clear if not needed. +- *Password:* \[Optional\] If required by the MQTT broker, this is the password with which you will be authenticated. Clear if not needed. +- *Topic:* \[Required\] The topic to which the pours will be published. diff --git a/docs/context/settings/targets/rpints/index.rst b/docs/context/settings/targets/rpints/index.rst deleted file mode 100644 index 33c6ac75..00000000 --- a/docs/context/settings/targets/rpints/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _rpints: - -Raspberry Pints Target -####################### - -.. image:: rpints.png - :scale: 25% - :align: center - :alt: Raspberry Pints Settings - -The Raspberry Pints page allows you to forward pours to an MQTT-enabled Raspberry Pints installation. The settings are as follows: - -- *Broker Address:* [Required] Enter the fully-qualified domain name of the Raspberry Pints target. You may use \*.local addresses, IP addresses, or Internet-facing addresses. -- *Broker Port:* [Required] The port to use, the default MQTT port is 1883. -- *User Name:* [Optional] If required by the MQTT broker, this is the user name by which you will be authenticated. Clear if not needed. -- *Password:* [Optional] If required by the MQTT broker, this is the password with which you will be authenticated. Clear if not needed. -- *Topic:* [Required] The topic to which the pours will be published. diff --git a/docs/context/settings/targets/taplistio/index.md b/docs/context/settings/targets/taplistio/index.md new file mode 100644 index 00000000..47bac3d7 --- /dev/null +++ b/docs/context/settings/targets/taplistio/index.md @@ -0,0 +1,18 @@ +(taplistio)= + +# Taplist.io Target + +```{image} taplistio.png +:align: center +:alt: Taplist.io Settings +:scale: 25% +``` + +The Taplist.io page allows you to forward pours to Taplist.io. The settings are as follows: + +- *Taplist.io Venue Name:* \[Required\] Venue/site name. Found in your account at taplist.io under Dashboard > Web Settings > Web Address. +- *Taplist.io Secret:* \[Required\] Taplistio API Secret. Generated in your account at taplist.io under Account > Integrations > API. Begins with 'secret-' (NOT 'key-'). + +In addition to the venue/secret, you must link each Keg Cop tap to a Taplist.io tap. This setting is configured on each tap's individual configuration tab. + +- *Taplist.io Tap Number:* \[Required\] Taplist.io tap number to link this tap to. Set to 0 to disable sending this tap. diff --git a/docs/context/settings/targets/taplistio/index.rst b/docs/context/settings/targets/taplistio/index.rst deleted file mode 100644 index 26ae299e..00000000 --- a/docs/context/settings/targets/taplistio/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _taplistio: - -Taplist.io Target -################# - -.. image:: taplistio.png - :scale: 25% - :align: center - :alt: Taplist.io Settings - -The Taplist.io page allows you to forward pours to Taplist.io. The settings are as follows: - -- *Taplist.io Venue Name:* [Required] Venue/site name. Found in your account at taplist.io under Dashboard > Web Settings > Web Address. -- *Taplist.io Secret:* [Required] Taplistio API Secret. Generated in your account at taplist.io under Account > Integrations > API. Begins with 'secret-' (NOT 'key-'). - - -In addition to the venue/secret, you must link each Keg Cop tap to a Taplist.io tap. This setting is configured on each tap's individual configuration tab. - -- *Taplist.io Tap Number:* [Required] Taplist.io tap number to link this tap to. Set to 0 to disable sending this tap. diff --git a/docs/context/settings/targets/url/index.rst b/docs/context/settings/targets/url/index.md similarity index 60% rename from docs/context/settings/targets/url/index.rst rename to docs/context/settings/targets/url/index.md index 511bccab..99c953d0 100644 --- a/docs/context/settings/targets/url/index.rst +++ b/docs/context/settings/targets/url/index.md @@ -1,11 +1,11 @@ -.. _url: +(url)= -URL Target -################# +# URL Target -.. image:: url.png - :scale: 50% - :align: center - :alt: +```{image} url.png +:align: center +:alt: true +:scale: 50% +``` A URL Target may be configured to receive a status post on a set schedule. Enter the full URL to the endpoint, and enter the frequency in minutes. diff --git a/docs/context/settings/temperature/control/index.rst b/docs/context/settings/temperature/control/index.md similarity index 61% rename from docs/context/settings/temperature/control/index.rst rename to docs/context/settings/temperature/control/index.md index a3ee5474..e8ae824d 100644 --- a/docs/context/settings/temperature/control/index.rst +++ b/docs/context/settings/temperature/control/index.md @@ -1,17 +1,17 @@ -.. _cooling: +(cooling)= -Temperature Control -##################### +# Temperature Control -.. image:: control.png - :scale: 50% - :align: center - :alt: Temperature Control +```{image} control.png +:align: center +:alt: Temperature Control +:scale: 50% +``` This page allows you to set temperature contol options. - **Set Point in (°F or °C)**: - - **Temperature**: Allows setting the desired system temperature setpoint. - - **Enabled/Disabled**: Turns temperature control on or off. + \- **Temperature**: Allows setting the desired system temperature setpoint. + \- **Enabled/Disabled**: Turns temperature control on or off. - **Control Point**: Select the teperature sensor by which the system will control. - **Invert Cooling Control**: The system defaults to "Normal" which means the cooling pin will go low when there is demand for cooling. Ths is the proper setting for typical relay boards, but the end user may desire to invert this and cool on high for a number of reasons. diff --git a/docs/context/settings/temperature/sensors/index.rst b/docs/context/settings/temperature/sensors/index.md similarity index 63% rename from docs/context/settings/temperature/sensors/index.rst rename to docs/context/settings/temperature/sensors/index.md index 0d383003..3add9e49 100644 --- a/docs/context/settings/temperature/sensors/index.rst +++ b/docs/context/settings/temperature/sensors/index.md @@ -1,12 +1,12 @@ -.. _sensors: +(sensors)= -Sensor Control -####################### +# Sensor Control -.. image:: sensors.png - :scale: 50% - :align: center - :alt: Temperature Sensor Settings +```{image} sensors.png +:align: center +:alt: Temperature Sensor Settings +:scale: 50% +``` You may apply a positive or negative calibration value individually for each temperature sensor. diff --git a/docs/context/temperatures/index.rst b/docs/context/temperatures/index.md similarity index 82% rename from docs/context/temperatures/index.rst rename to docs/context/temperatures/index.md index 845a8f13..02f6220d 100644 --- a/docs/context/temperatures/index.rst +++ b/docs/context/temperatures/index.md @@ -1,16 +1,16 @@ -.. _temperatures: +(temperatures)= -Temperatures -#################### +# Temperatures -.. image:: temperatures.png - :scale: 50% - :align: center - :alt: System Temperatures +```{image} temperatures.png +:align: center +:alt: System Temperatures +:scale: 50% +``` If you have configured the Keg Cop system with temperature sensors, you may navigate to this page with the Temperature Sensor link on the main menu. Its presence in the main menu bar is dynamic, so it will only appear after a page loads completely. -There is also a link to the Temperature page via the temperature display and cooling status box in the top-right corner of the home page. +There is also a link to the Temperature page via the temperature display and cooling status box in the top-right corner of the home page. The Temperature Sensors page displays a bar for each active temperature sensor. If you have configured the system to control temperatures, a horizontal bar will appear across the chart showing the setpoint. diff --git a/docs/contributions/index.rst b/docs/contributions/index.md similarity index 75% rename from docs/contributions/index.rst rename to docs/contributions/index.md index acce28ba..22ab1a52 100644 --- a/docs/contributions/index.rst +++ b/docs/contributions/index.md @@ -1,10 +1,9 @@ -.. _contributions: +(contributions)= -Contributions -################### +# Contributions This documentation remains a work in progress, in that I depend on *you* to help me make sure it is relevant and easy to read. I know how to work with Keg Cop. My goal is to make you an expert too. Anything that is confusing is a bug, and I want to know about it, please. -For spelling/grammatical errors, or if you would like to improve the documentation, please feel free to issue a pull request with the update. For technical issues with this documentation, please `open an issue on GitHub`_. +For spelling/grammatical errors, or if you would like to improve the documentation, please feel free to issue a pull request with the update. For technical issues with this documentation, please [open an issue on GitHub]. -.. _open an issue on GitHub: https://github.com/lbussy/keg-cop/issues +[open an issue on github]: https://github.com/lbussy/keg-cop/issues diff --git a/docs/firmware/index.md b/docs/firmware/index.md new file mode 100644 index 00000000..0b30c37a --- /dev/null +++ b/docs/firmware/index.md @@ -0,0 +1,50 @@ +(firmware)= + +# Installing the Firmware + +Flashing the firmware may be done from many platforms with a variety of tools. The following is a method that have I have tested. Other methods may work; however, I have less experience with them. + +Important Note: + +: The ESP32 has a memory section which is not erased or written over by flashing firmware. If you have previously used your controller for any other tasks, I recommend that you wipe the flash memory before you begin. The method to do that differs by the tool used, and more information follows in the sections below. + +**Before proceeding, connect your controller via the USB port to your workstation.** + +## Preferred Method for Windows and Macs + +[BrewFlasher] is a stand-alone desktop application for Windows and macOS designed to simplify flashing Keg Cop (And other brewing-related firmware) to your controller. + +It handles everything - locating the correct firmware, downloading it, setting the correct flash options/offsets, and flashing the firmware. There is no fumbling with the command line or worrying about esptool options. Select the project you want to flash, click a button, and you have finished. + +You may download [BrewFlasher] from its GitHub release page or [BrewFlasher.com]. + +:::{figure} bf_gui.png +:align: center +:alt: BrewFlasher for Windows and MacOS +:scale: 40% +::: + +You will use the following settings: + +- Serial port: Auto-select +- Project: Key Cop +- Device Family: ESP32 +- Firmware: Keg Cop (latest version) +- Baud rate: 921600 (any should work, this is faster) +- Flash mode: Dual I/O (DIO) +- Erase flash: yes, wipes all data (this avoids problems later on - it will wipe wifi settings if any) + +Now click the button that says, "Download Firmware and Flash Controller." + +[Here] is a short video produced by the author of BrewFlasher. + +## Firmware Updates + +The web application provides Over The Air (OTA) update functionality for upgrades. Navigate to the *Settings* page and on the *Adanced* menu, select *Update Application*. + +[brewflasher]: https://github.com/thorrak/brewflasher +[brewflasher.com]: https://www.brewflasher.com/ +[download]: https://www.espressif.com/en/support/download/other-tools +[esptool]: https://github.com/espressif/esptool +[here]: https://youtu.be/7KZiRoxn-z8 +[repository]: https://github.com/espressif/esptool diff --git a/docs/firmware/index.rst b/docs/firmware/index.rst deleted file mode 100644 index 777e5a3e..00000000 --- a/docs/firmware/index.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. _firmware: - -Installing the Firmware -======================= - -Flashing the firmware may be done from many platforms with a variety of tools. The following is a method that have I have tested. Other methods may work; however, I have less experience with them. - -Important Note: - The ESP32 has a memory section which is not erased or written over by flashing firmware. If you have previously used your controller for any other tasks, I recommend that you wipe the flash memory before you begin. The method to do that differs by the tool used, and more information follows in the sections below. - -**Before proceeding, connect your controller via the USB port to your workstation.** - -Preferred Method for Windows and Macs --------------------------------------- - -BrewFlasher_ is a stand-alone desktop application for Windows and macOS designed to simplify flashing Keg Cop (And other brewing-related firmware) to your controller. - -It handles everything - locating the correct firmware, downloading it, setting the correct flash options/offsets, and flashing the firmware. There is no fumbling with the command line or worrying about esptool options. Select the project you want to flash, click a button, and you have finished. - -You may download BrewFlasher_ from its GitHub release page or BrewFlasher.com_. - -.. figure:: bf_gui.png - :scale: 40% - :align: center - :alt: BrewFlasher for Windows and MacOS - -You will use the following settings: - -- Serial port: Auto-select -- Project: Key Cop -- Device Family: ESP32 -- Firmware: Keg Cop (latest version) -- Baud rate: 921600 (any should work, this is faster) -- Flash mode: Dual I/O (DIO) -- Erase flash: yes, wipes all data (this avoids problems later on - it will wipe wifi settings if any) - -Now click the button that says, "Download Firmware and Flash Controller." - -Here_ is a short video produced by the author of BrewFlasher. - -Firmware Updates ----------------- - -The web application provides Over The Air (OTA) update functionality for upgrades. Navigate to the *Settings* page and on the *Adanced* menu, select *Update Application*. - -.. _BrewFlasher: https://github.com/thorrak/brewflasher -.. _BrewFlasher.com: https://www.brewflasher.com/ -.. _esptool: https://github.com/espressif/esptool -.. _repository: https://github.com/espressif/esptool -.. _download: https://www.espressif.com/en/support/download/other-tools -.. _Here: https://youtu.be/7KZiRoxn-z8 diff --git a/docs/index.rst b/docs/index.md similarity index 73% rename from docs/index.rst rename to docs/index.md index 97c9cc99..4551256c 100644 --- a/docs/index.rst +++ b/docs/index.md @@ -1,38 +1,40 @@ -.. image:: keg_cop.png - :scale: 100% - :align: center - :alt: Keg Cop Logo +```{image} keg_cop.png +:align: center +:alt: Keg Cop Logo +:scale: 100% +``` -About Keg Cop -################### +# About Keg Cop We like to brew. Arguably, that means we want to drink. Sure, we can go down to the corner store and buy beer, but that's not in our nature. We spend eight hours brewing to spend a couple of hours enjoying our craft with our friends. Don't try to justify it, or figure out why. It just is. Invariably, the homebrewer moves from cleaning and filling 24 bottles at a time, to filling one big bottle - a keg. The problem with that, for all the benefits, is that we cannot quickly tell how much is left. We can open the keezer and try to guess by lifting it, but that is inaccurate, potentially dangerous, and sometimes impossible. Keg Cop watches your kegs and tells you exactly how much of your precious brew is left. -.. image:: home.png - :scale: 50% - :align: center - :alt: Keg Cop Home +```{image} home.png +:align: center +:alt: Keg Cop Home +:scale: 50% +``` At the core, Keg Cop is a small, inexpensive microcontroller far more capable than the computers used for the Apollo moon missions. You connect the controller to one or more flow meters. Keg Cop makes incredibly precise measurements while you dispense your beer. The capacity and amount remaining in each display on a compact and mobile responsive web page. Optionally, you may configure Keg Cop to upload data to several other systems. Keg Cop is an entirely Free and Open Source offering. I have provided all source files, including optional 3D printed parts. You can build this, what follows is the how. -.. toctree:: - :maxdepth: 1 - :caption: Table of Contents: - :titlesonly: - :glob: - - planning/index - pcbassembly/index - firmware/index - networking/index - sysassembly/index - operations/index - api/index - troubleshooting/index - context/index - contributions/index - todo +```{toctree} +:caption: 'Table of Contents:' +:glob: true +:maxdepth: 1 +:titlesonly: true + +planning/index +pcbassembly/index +firmware/index +networking/index +sysassembly/index +operations/index +api/index +troubleshooting/index +context/index +contributions/index +todo +``` diff --git a/docs/networking/index.rst b/docs/networking/index.md similarity index 75% rename from docs/networking/index.rst rename to docs/networking/index.md index 54952535..83895a0f 100644 --- a/docs/networking/index.rst +++ b/docs/networking/index.md @@ -1,93 +1,93 @@ -.. _networking: +(networking)= -Set Up Networking -##################### +# Set Up Networking After flashing the firmware for the first time or erasing network settings, your controller will not participate in any WiFi networks. It starts in what is called "Access Point (AP) Mode," where it serves as a sort of stand-alone wireless network. The onboard LED will flash at 0.5Hz, or one second on, one second off. -Initial Network Settings -************************** +## Initial Network Settings You may use any wireless-capable device to connect to the access point. However, you may achieve the best results using a mobile device. In the following examples, I use an iPhone; however, any device should be very similar. Be aware that using the same machine to follow these instructions may result in the instructions not being available when you connect to the Keg Cop AP. No Internet will be available to your phone or laptop while you go through the process. In your device settings, search for an available access point named "kegcop." -.. image:: 1_choose_ap.png - :scale: 25% - :align: center - :alt: Search Access Points +```{image} 1_choose_ap.png +:align: center +:alt: Search Access Points +:scale: 25% +``` Connect to the "kegcop" network, and when prompted, enter the password "kegcop21." -.. image:: 2_ap_pwd.png - :scale: 25% - :align: center - :alt: Enter AP Password +```{image} 2_ap_pwd.png +:align: center +:alt: Enter AP Password +:scale: 25% +``` Your device should connect and briefly show that connection before proceeding. -.. image:: 2a_ap_pwd.png - :scale: 25% - :align: center - :alt: Enter AP Password +```{image} 2a_ap_pwd.png +:align: center +:alt: Enter AP Password +:scale: 25% +``` When you connect to the Keg Cop AP, your mobile device or computer should detect it as a "captive portal." Any DNS queries made will always return the AP's IP address, similar to using free WiFi at a restaurant. Your device or computer should open a web browser and connect to the captive portal. If not, open a web browser and connect to the IP address 192.168.4.1. The captive portal will show, allowing you to continue. -.. image:: 3_captive_portal.png - :scale: 20% - :align: center - :alt: Captive Portal +```{image} 3_captive_portal.png +:align: center +:alt: Captive Portal +:scale: 20% +``` On the portal page, select "Configure WiFi" to continue. -.. image:: 4_configure_wifi.png - :scale: 20% - :align: center - :alt: Configure WiFi +```{image} 4_configure_wifi.png +:align: center +:alt: Configure WiFi +:scale: 20% +``` You should see a list of nearby wireless networks. Select your WiFi network, and the SSID of the network will populate the SSID field. Next, enter your WiFi password. You may also perform a static IP configuration on this page. Such a setup should be used only by those who understand the implications and can determine and test the proper settings. -.. image:: 5_wifi_pwd.png - :scale: 20% - :align: center - :alt: WiFi Password +```{image} 5_wifi_pwd.png +:align: center +:alt: WiFi Password +:scale: 20% +``` Click the "Save" button. -.. image:: 6_wait_for_connect.png - :scale: 20% - :align: center - :alt: Wait For Connect +```{image} 6_wait_for_connect.png +:align: center +:alt: Wait For Connect +:scale: 20% +``` -The controller will attempt to connect to the network. If the connection is successful, the Keg Cop AP will go away, and your device should connect to your last known good connection. You may have to reconnect your computer or phone manually. In the case of the iPhone, if the Keg Cop does not connect to your local wireless, the AP will not terminate, and your browser will remain on this screen. You can hit the back ("<") arrow to return to the WiFi configuration and try again. +The controller will attempt to connect to the network. If the connection is successful, the Keg Cop AP will go away, and your device should connect to your last known good connection. You may have to reconnect your computer or phone manually. In the case of the iPhone, if the Keg Cop does not connect to your local wireless, the AP will not terminate, and your browser will remain on this screen. You can hit the back ("\<") arrow to return to the WiFi configuration and try again. -If all goes as expected, the controller's LED will flash as it performs various configuration steps, and finally, the LED will remain off. Here you may proceed. If you have issues, check the :ref:`troubleshooting ` page for more information. +If all goes as expected, the controller's LED will flash as it performs various configuration steps, and finally, the LED will remain off. Here you may proceed. If you have issues, check the {ref}`troubleshooting ` page for more information. -Network Settings Change -************************** +## Network Settings Change At some point, you may need to change your WiFi settings. Remembering to do it while you are still able to connect to the application is simplest. However, you may raise the access point without being able to access the Keg Cop Application. -Reset Settings -================ +### Reset Settings -The easiest way to change settings is to access the Keg Cop web page. In Settings > Advanced > Reset Wifi you may :ref:`reset wifi settings `. After that, you can re-join the Keg Cop soft AP and configure a new network. +The easiest way to change settings is to access the Keg Cop web page. In Settings > Advanced > Reset Wifi you may {ref}`reset wifi settings `. After that, you can re-join the Keg Cop soft AP and configure a new network. -Re-Raise AP -================ +### Re-Raise AP If the Keg Cop controller cannot access the configured WiFi network, it should drop into AP mode and allow configuration. It will indicate this by the AP-mode flashing (0.5Hz) of the onboard LED. If this does not work, or if you prefer, you may raise the AP by a double-reset press or an electrical connection. -Double-Reset Detect ---------------------- +#### Double-Reset Detect If you press the reset button twice within three seconds, the device will enter AP mode and begin flashing (0.5Hz) the onboard LED. The reset presses need not be fast; it will likely work more reliably if you leave 0.5-1.0 seconds between presses. -Electrical Connection ----------------------- +#### Electrical Connection Take a piece of wire and short pin 13 to ground. Then with the wire connected, reset the controller by pressing the reset button or cycling power. The controller will detect pin 13 being low on startup, enter AP mode, and begin flashing (0.5Hz) the onboard LED. You can disconnect the wire and proceed with the configuration. diff --git a/docs/operations/index.md b/docs/operations/index.md new file mode 100644 index 00000000..4cd688cf --- /dev/null +++ b/docs/operations/index.md @@ -0,0 +1,52 @@ +(operations)= + +# Operations and Configuration + +```{image} settings.png +:align: center +:alt: Settings Page +:scale: 60% +``` + +At a minimum, you will want to look at the settings menu to set up your new device. See the links below for a description of each option. + +{ref}`Controller `: + +- Hostname +- Brewery name +- Kegerator/Keezer name +- Units of measure +- Reporting functionality + +{ref}`Taps `: + +- Pulses per unit of measure +- Beverage name +- Capacity of keg +- Remaining in keg +- Tap active/inactive + +{ref}`Temperature Control `: + +- Set point +- Control point +- Control enabled/disabled + +{ref}`Temperature Sensors `; + +- Calibration +- Enabled/disabled + +Targets: + +- {ref}`KegScreen Target ` +- {ref}`URL Target ` +- {ref}`Raspberry Pints Target ` +- {ref}`Taplist.io ` + +Advanced + +- {ref}`Calibrate flowmeters ` +- {ref}`Reset controller ` +- {ref}`Update application ` +- {ref}`Reset WiFi ` diff --git a/docs/operations/index.rst b/docs/operations/index.rst deleted file mode 100644 index 98ddff57..00000000 --- a/docs/operations/index.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. _operations: - -Operations and Configuration -################################# - -.. image:: settings.png - :scale: 60% - :align: center - :alt: Settings Page - -At a minimum, you will want to look at the settings menu to set up your new device. See the links below for a description of each option. - -:ref:`Controller `: - -- Hostname -- Brewery name -- Kegerator/Keezer name -- Units of measure -- Reporting functionality - -:ref:`Taps `: - -- Pulses per unit of measure -- Beverage name -- Capacity of keg -- Remaining in keg -- Tap active/inactive - -:ref:`Temperature Control `: - -- Set point -- Control point -- Control enabled/disabled - -:ref:`Temperature Sensors `; - -- Calibration -- Enabled/disabled - -Targets: - -- :ref:`KegScreen Target ` -- :ref:`URL Target ` -- :ref:`Raspberry Pints Target ` -- :ref:`Taplist.io ` - -Advanced - -- :ref:`Calibrate flowmeters ` -- :ref:`Reset controller ` -- :ref:`Update application ` -- :ref:`Reset WiFi ` diff --git a/docs/pcbassembly/index.rst b/docs/pcbassembly/index.md similarity index 52% rename from docs/pcbassembly/index.rst rename to docs/pcbassembly/index.md index 8a84c036..75111bea 100644 --- a/docs/pcbassembly/index.rst +++ b/docs/pcbassembly/index.md @@ -1,88 +1,83 @@ -.. _pcb: +(pcb)= -PCB Assembly -##################### +# PCB Assembly Keg Cop runs on an ESP32 controller. To detect the information to be logged, you need to connect specific devices to the controller. I have provided a main circuit board design, as well as several breakouts for your use. Assembly is not difficult, but it does require some basic soldering. -Materials Required -********************* +## Materials Required This project uses widely-available and inexpensive components. You may find you are better off buying a resistor assortment, for instance, or buying 10 or 20 of a piece at a time for a nominal cost from China. You will need to order the printed circuit boards from a supply house. The heart of the system is, of course, the controller. -Because there are multiple ways to configure this Keg Cop system, I will demonstrate using my single Kegerator, three taps, and a temperature control setup. Other configurations may be detailed on the :ref:`planning ` page. +Because there are multiple ways to configure this Keg Cop system, I will demonstrate using my single Kegerator, three taps, and a temperature control setup. Other configurations may be detailed on the {ref}`planning ` page. Gather the following parts and pieces to get started: -Controller -============ +### Controller The ESP32 controller is paired with many different "developer boards" to make connections easier. While you can buy a bare ESP32 chip, you will walk that road alone. The developer board used in this project is the Lolin D32 v1.0.0 (not the Pro or 2.0.) Wherever you purchase it, make sure it is an official Espressif ESP32-WROOM-32 Module. It says 4MB (or sometimes shown as 32Mb, which is 4 megaBYTES converted to megaBITS.) There is a version sometimes called "LED," which means there is an annoying blinking LED when a battery is not connected. It will work, and so long as it's in a case, you won't notice the blinking. Be sure it comes with the 16-pin male and female headers, or get them elsewhere. It is common to only receive the male headers in the package. -.. image:: lolin_d32.jpg - :scale: 50% - :align: center - :alt: Lolin D32 v1.0.0 +```{image} lolin_d32.jpg +:align: center +:alt: Lolin D32 v1.0.0 +:scale: 50% +``` -You can find the Lolin D32 in many places. Lolin D32 is one of maybe hundreds of development boards. Their prime delivery method to hobbyists seems to be `the Lolin store on AliExpress `_. +You can find the Lolin D32 in many places. Lolin D32 is one of maybe hundreds of development boards. Their prime delivery method to hobbyists seems to be [the Lolin store on AliExpress](https://www.aliexpress.com/item/32808551116.html). -AliExpress also seems to be the least expensive path, but of course, ordering direct from China does take a bit longer than other methods. You will spend more but get your hands on the device quicker if you purchase from `Amazon `_ or any other place you can find it. +AliExpress also seems to be the least expensive path, but of course, ordering direct from China does take a bit longer than other methods. You will spend more but get your hands on the device quicker if you purchase from [Amazon](https://www.amazon.com/Genuine-Original-LOLIN-D32-V2-0-0/dp/B07T1SCXYW) or any other place you can find it. -Printed Circuit Boards -========================== +### Printed Circuit Boards This configuration will use the following three boards: -- `Main Board `_ -- `Sensor board `_ -- 3 x `Daisy Chain boards `_ +- [Main Board](https://oshpark.com/shared_projects/UQZn4ng4) +- [Sensor board](https://oshpark.com/shared_projects/MkSWgv0t) +- 3 x [Daisy Chain boards](https://oshpark.com/shared_projects/Zc4zPNjI) The links will take you to OshPark where I have uploaded the designs. OshPark is not the cheapest, but they are the most consistent fab house I have dealt with. You're only talking the difference of a few dollars in your project between them and other fab houses. For my peace of mind, and for me to recommend them to you, I think it's worth it. You may take the files from GitHub and upload them yourself somewhere else to save money if you choose. -Components -================ +### Components For this configuration, we will use the following components: **Main Board:** -- 2 x `2.54mm Pitch Single Row Female 16P PCB socket Board Pin Header Connector Strip Pinheader 2/3/4/6/10/12/16/20/40Pin For Arduino `_ (D32) (Note: Multiple items on the page, be sure to select the proper item) -- 2 x `0.1μF (1.0nF) Ceramic Capacitor (102) 2.54mm spacing `_ (C1, 3) (Note: The same link as below, select the proper item) -- 2 x `1.0μF Ceramic Capacitor (105) 2.54mm spacing `_ (C2, C4) (Note: The same link as above, select the proper item) -- \*1 x `DS18B20 PCB-mount sensor `_ (IC1) (Note: Multiple items on the page, be sure to select the proper item) -- 14 x `2.2kΩ 1/4W 5% Axial Resistor `_ (R1-R5) (Note: Multiple items on the page, be sure to select the proper item) -- 4 x `RJ45 8-pin 90° no shield PCM-mount jack `_ -- 1 x `2-pin Straight Male Header `_ (POWER) (Note: More than enough in one lot for all three headers) -- \*1 x `3-pin Straight Male Header `_ (ROOM) (Note: More than enough in one lot for all three headers) -- 1 x `4-pin Straight Male Header `_ (RELAY) (Note: More than enough in one lot for all three headers) +- 2 x [2.54mm Pitch Single Row Female 16P PCB socket Board Pin Header Connector Strip Pinheader 2/3/4/6/10/12/16/20/40Pin For Arduino](https://www.aliexpress.com/item/1005001418544370.html?algo_exp_id=d7709a47-14ca-46e1-bdcb-fe609affb88a-0) (D32) (Note: Multiple items on the page, be sure to select the proper item) +- 2 x [0.1μF (1.0nF) Ceramic Capacitor (102) 2.54mm spacing](https://www.aliexpress.com/item/32868001945.html) (C1, 3) (Note: The same link as below, select the proper item) +- 2 x [1.0μF Ceramic Capacitor (105) 2.54mm spacing](https://www.aliexpress.com/item/32868001945.html) (C2, C4) (Note: The same link as above, select the proper item) +- \*1 x [DS18B20 PCB-mount sensor](https://www.aliexpress.com/item/1901263688.html) (IC1) (Note: Multiple items on the page, be sure to select the proper item) +- 14 x [2.2kΩ 1/4W 5% Axial Resistor](https://www.aliexpress.com/item/32660635741.html) (R1-R5) (Note: Multiple items on the page, be sure to select the proper item) +- 4 x [RJ45 8-pin 90° no shield PCM-mount jack](https://www.aliexpress.com/item/32736146888.html) +- 1 x [2-pin Straight Male Header](https://www.aliexpress.com/item/2040310671.html) (POWER) (Note: More than enough in one lot for all three headers) +- \*1 x [3-pin Straight Male Header](https://www.aliexpress.com/item/2040310671.html) (ROOM) (Note: More than enough in one lot for all three headers) +- 1 x [4-pin Straight Male Header](https://www.aliexpress.com/item/2040310671.html) (RELAY) (Note: More than enough in one lot for all three headers) -If you want the convenience of one-click ordering from the US, the BOM for the main board parts (not the PCB itself) may be purchased from `Mouser `_. This does not include the DS18B20 temperature sensor. +If you want the convenience of one-click ordering from the US, the BOM for the main board parts (not the PCB itself) may be purchased from [Mouser](https://www.mouser.com/ProjectManager/ProjectDetail.aspx?AccessID=7085525c8d). This does not include the DS18B20 temperature sensor. **Sensor Board:** -- 1 x `RJ45 8-pin 90° no shield PCM-mount jack `_ -- 4 x `3-pin terminal block `_ -- \*4 x `DS1820 Stainless steel package Waterproof DS18b20 temperature probe `_ (Note: Multiple items on the page, be sure to select the proper item) +- 1 x [RJ45 8-pin 90° no shield PCM-mount jack](https://www.aliexpress.com/item/32736146888.html) +- 4 x [3-pin terminal block](https://www.aliexpress.com/item/32965348107.html) +- \*4 x [DS1820 Stainless steel package Waterproof DS18b20 temperature probe](https://www.aliexpress.com/item/4000895660165.html?algo_exp_id=4e52347a-1295-44ca-8766-1ef0f244c1d2-1) (Note: Multiple items on the page, be sure to select the proper item) -If you want the convenience of one-click ordering from the US, the BOM for the sensor board (not the PCB itself) may be purchased from `Mouser `_. This does not include the DS18B20 temperature sensors. +If you want the convenience of one-click ordering from the US, the BOM for the sensor board (not the PCB itself) may be purchased from [Mouser](https://www.mouser.com/ProjectManager/ProjectDetail.aspx?AccessID=db4e1f22c9). This does not include the DS18B20 temperature sensors. **Daisy Chain Boards (per flowmeter, multiply all numbers x 3 for three flowmeters):** -- 2 x `RJ45 8-pin 90° no shield PCM-mount jack `_ -- 1 x `3-pin terminal block `_ +- 2 x [RJ45 8-pin 90° no shield PCM-mount jack](https://www.aliexpress.com/item/32736146888.html) +- 1 x [3-pin terminal block](https://www.aliexpress.com/item/32965348107.html) -If you want the convenience of one-click ordering from the US, the BOM for the daisy-chain board (not the PCB itself) may be purchased from `Mouser `_. You will need one of this list per flowmeter. +If you want the convenience of one-click ordering from the US, the BOM for the daisy-chain board (not the PCB itself) may be purchased from [Mouser](https://www.mouser.com/ProjectManager/ProjectDetail.aspx?AccessID=92f043e4f8). You will need one of this list per flowmeter. -(*) - Optional items for use when you desire a room temperature sensor. Either use a DS18B20 sensor with a lead or a PCB-mount sensor - the sensor on a lead is recommended to avoid invalid readings due to heat from the controller. +(\*) - Optional items for use when you desire a room temperature sensor. Either use a DS18B20 sensor with a lead or a PCB-mount sensor - the sensor on a lead is recommended to avoid invalid readings due to heat from the controller. -Soldering -=========== +### Soldering -You are going to have to solder. If you have legitimately never soldered anything before, I recommend you spend a few minutes on YouTube and watch a few videos. `Sparkfun `_ also has a very nice `tutorial `_. It is not hard at all once you get the hang of it. And, while the boards are comparatively small, the components chosen are simple through-hole parts, which may be easily soldered by a beginner with a little patience. +You are going to have to solder. If you have legitimately never soldered anything before, I recommend you spend a few minutes on YouTube and watch a few videos. [Sparkfun](https://learn.sparkfun.com/) also has a very nice [tutorial](https://learn.sparkfun.com/tutorials/how-to-solder-through-hole-soldering). It is not hard at all once you get the hang of it. And, while the boards are comparatively small, the components chosen are simple through-hole parts, which may be easily soldered by a beginner with a little patience. Be sure to use flux when you solder. Liquid flux is the easiest to use. Be sure to get both sides of the board because you want the solder to flow to both sides. After you solder from behind, flip the board over to make sure you get a good flow. If not, you can always touch up from the top (but don't tell anyone you cheated.) @@ -98,7 +93,6 @@ When you solder the sensor board, you have a choice. I designed it to orient the Once you have finished soldering the shield, make sure to clean off the flux. You can use cheap vodka or Everclear, or a commercially available flux solvent. -Modifications -*************** +## Modifications -The `pcb directory `_ in the repository contains the Eagle files for the printed circuit board shield supporting Keg Cop. You can download the design files, modify them, and upload them to the PCB manufacturer of your choice. If you would like to personalize these board designs, you may edit them with Autodesk's EAGLE. EAGLE is a scriptable electronic design automation (EDA) application with schematic capture, printed circuit board (PCB) layout, auto-router, and computer-aided manufacturing (CAM) features. EAGLE stands for Easily Applicable Graphical Layout Editor and is developed by CadSoft Computer GmbH. +The [pcb directory](https://github.com/lbussy/keg-cop/tree/master/pcb) in the repository contains the Eagle files for the printed circuit board shield supporting Keg Cop. You can download the design files, modify them, and upload them to the PCB manufacturer of your choice. If you would like to personalize these board designs, you may edit them with Autodesk's EAGLE. EAGLE is a scriptable electronic design automation (EDA) application with schematic capture, printed circuit board (PCB) layout, auto-router, and computer-aided manufacturing (CAM) features. EAGLE stands for Easily Applicable Graphical Layout Editor and is developed by CadSoft Computer GmbH. diff --git a/docs/planning/index.rst b/docs/planning/index.md similarity index 62% rename from docs/planning/index.rst rename to docs/planning/index.md index 264afd60..04aced54 100644 --- a/docs/planning/index.rst +++ b/docs/planning/index.md @@ -1,14 +1,14 @@ -.. _planning: +(planning)= -Project Planning -#################### +# Project Planning Keg Cop is capable of a wide variety of configurations. Each has similar building blocks, and you may apply that methodology to a variety of applications. Here is a system with two flow meters, a room temp sensor, a keg temp sensor, a chamber sensor, cooling control, and a solenoid. -.. image:: system.png - :scale: 15% - :align: center - :alt: System Diagram +```{image} system.png +:align: center +:alt: System Diagram +:scale: 15% +``` It would be best if you did a little planning before you begin. Keg Cop is configurable and extensible, and as such, you should know what you hope to achieve. @@ -16,13 +16,12 @@ It would be best if you did a little planning before you begin. Keg Cop is conf - **Temp Sensor Choice**: Since this system provides temperature control of your keg chamber, temperature sensors are naturally supported and required for temperature control. Keg Cop supports up to five temperature sensors, including one for room temperature. - **Main Board - One main board per system:**: It provides a single Ethernet going to the flowmeter chain and another Ethernet port connecting to the chamber sensors. A temperature sensor for Room temperature mounted to the board. - **Sensor/Meter Boards - Connectors to the physical aspects of the system:** - - Daisy-Chain Boards: These small boards, one per flowmeter, connect the flowmeter(s) into the system. There is an "In" and an "Out" connector, creating a chain of up to nine sensors. The first on the chain is always number one, and so on. + : - Daisy-Chain Boards: These small boards, one per flowmeter, connect the flowmeter(s) into the system. There is an "In" and an "Out" connector, creating a chain of up to nine sensors. The first on the chain is always number one, and so on. - Sensor Board: This is a breakout board for connecting up to five temperature sensors. -The BOM for the electronics may be found on the :doc:`PCB Assembly ` page. +The BOM for the electronics may be found on the {doc}`PCB Assembly ` page. -Flowmeters -************* +## Flowmeters The flowmeter is probably the single most important and yet the most challenging part to source. It's not because flowmeters are hard to find; it's because there are so many choices. Your choices will dictate some of the operations choices for the application. @@ -30,20 +29,15 @@ Keg Cop will support a different flowmeter on each tap if that's how you want to You can choose from any number of flowmeters using a single data (pulse/frequency) line and powered from 3V3. Some choices used by the homebrewing community include: -- Swissflow SF800_ Low-Pressure Flow Meter -- YF-S401_ Water Flow Sensor Meter Flowmeter Coffee Dispenser Counter 0.3-6 L/min (eBay) -- Liquid Flow Meter - Plastic 1/2" NPS Threaded ID: 828_ (Adafruit) +- Swissflow [SF800] Low-Pressure Flow Meter +- [YF-S401] Water Flow Sensor Meter Flowmeter Coffee Dispenser Counter 0.3-6 L/min (eBay) +- Liquid Flow Meter - Plastic 1/2" NPS Threaded ID: [828] (Adafruit) While one or two of the above links may eventually grow stale, what is listed should give you enough information to find a suitable device. Swissflow is probably the most expensive device. However, it is likely the most accurate one available. To be completely transparent, they helped my development by defraying a portion of my meters' expenses. I would have purchased them at the list price if they had not. Buy once, cry once, as my grandfather used to say. -.. _SF800: http://www.swissflow.com/sf800.html -.. _YF-S401: https://www.ebay.com/itm/YF-S401-Water-Flow-Sensor-Meter-Flowmeter-Coffee-Dispenser-Counter-0-3-6-L-min/282112630770 -.. _828: https://www.adafruit.com/product/828 - -A Practical Example -*********************** +## A Practical Example Take, for example, my three-tap kegerator. I need to decide whether or not I will use temperature sensors. I do want to use Keg Cop to control my Kegerator temperatures, so I know I need both a sensor board and one daisy chain board per flow meter. My setup therefore is: @@ -53,39 +47,43 @@ Take, for example, my three-tap kegerator. I need to decide whether or not I wil If you have a similar setup, you may always add new Daisy Chain boards as needed. The most appropriate installation uses one Keg Cop per kegerator/keezer. If you are fortunate enough to have more than one kegerator, plan for separate Keg Cop systems. -Why This Approach? -******************* +## Why This Approach? -I polled the community some time back, asking `how many kegs people had in their kegerator/keezer `_. I learned that most people have four kegs per unit (27.8%) with three kegs coming in a close second (25%). Eighty-seven percent (87.5) of the respondents had seven or fewer kegs. In hindsight, I should have set up the poll with a clear separation between having eight kegs and having nine or more, but nobody is perfect. +I polled the community some time back, asking [how many kegs people had in their kegerator/keezer](https://www.homebrewtalk.com/threads/how-many-kegs-in-your-keezer-kegerator.672039/). I learned that most people have four kegs per unit (27.8%) with three kegs coming in a close second (25%). Eighty-seven percent (87.5) of the respondents had seven or fewer kegs. In hindsight, I should have set up the poll with a clear separation between having eight kegs and having nine or more, but nobody is perfect. -.. image:: kegs_per_chamber.png - :scale: 100% - :align: center - :alt: Kegs per Chamber +```{image} kegs_per_chamber.png +:align: center +:alt: Kegs per Chamber +:scale: 100% +``` -In another thread, I asked `how many kegerators or keezers people had `_. This poll showed that the vast majority of homebrewers have a single chamber (52.2%), with less than a quarter of the respondents (21.7%) having two. I feel that the approach I have taken of one per chamber is reasonable and will not be burdensome. +In another thread, I asked [how many kegerators or keezers people had](https://www.homebrewtalk.com/threads/how-many-kegerators-keezers.672043/). This poll showed that the vast majority of homebrewers have a single chamber (52.2%), with less than a quarter of the respondents (21.7%) having two. I feel that the approach I have taken of one per chamber is reasonable and will not be burdensome. -.. image:: number_of_chambers.png - :scale: 100% - :align: center - :alt: Kegs per Chamber +```{image} number_of_chambers.png +:align: center +:alt: Kegs per Chamber +:scale: 100% +``` There are always edge cases, people with morgue-sized chest freezers in each room with ten kegs. My feeling is that these people have already invested a significant amount in their systems. These homebrewers are used to things just being more complicated at scale, and having multiple Keg Cops is the least of their worries. -Design Limitations -******************* +## Design Limitations There are also some practical considerations to these design constraints: - **Off the shelf cabling:** The cabling method is what I consider a shortcoming in some DIY projects. One often finds instructions to "connect the widget arm to the maniform" without any indication of how to do it. Illustrations invariably show a rainbow of DuPont wires plugged into a breadboard. That's fine for development work but does not address real-life needs. People need a prescriptive method to connect components. It should be simple, prevent crossed circuits, and not have an entry cost for tooling, which creates hidden costs. Ethernet cables check almost all our needs. They are straight-through (where phone cords have a crossover) and can be purchased locally or online. They are also available in many lengths and have a reasonably secure connection mechanism. - **Cabling Capacity:** Having chosen the prescribed cabling, this does create an inherent limitation. An Ethernet cable has eight wires. A flowmeter has power and ground, shared across each meter, plus a discrete data line. Each data line needs a paired ground with which it is twisted within the bundle to prevent electrical interference. That means a single Ethernet cable can serve a maximum of three flowmeters. A similar situation exists with the temperature sensors. Using all available temperature sensor slots consumes seven of the eight available wires. - **Controller Capacity:** - - A controller has a given number of pins with which to interact with the physical world. Some pins also have a function internal to the controller or the development board (such as the LED.) This project uses almost all available pins on the chosen ESP32 development board. - - The OneWire sensors I use for temperatures could work with all sensors on a single wire for data (hence the "OneWire" name.) You are familiar with the slight inconvenience this poses if you have used one of the various fermentation temperature controllers. You have to connect one sensor at a time and assign its use, or heat/cool one sensor at a time so that you can label it. Each sensor has an internal address that allows it to be assigned to a specific use or name; however, figuring out which one is a little cumbersome. I wanted a more straightforward method of one sensor per pin so that there is an explicit physical configuration without such addressing concerns. Because of this approach, I have reserved five controller pins for temperature sensors. - - The flow meters do not have any method of resolving a sensor. The data pin pulses as the flow is detected. On the controller, we use one pin per sensor to catch each pulse independent of the others. Therefore, I have reserved nine pins for flow meters. - - Temperature control means that there needs to be a method of turning on and off the cooling. One pin is used for this to control a relay. - - Solenoid control is a feature that exists in many of the previous keg display systems. Because of the keg lines' proximity, this device seemed like the appropriate place to put the solenoid control. We use one pin for this, intended to turn on or off all solenoids at once using a relay. + : - A controller has a given number of pins with which to interact with the physical world. Some pins also have a function internal to the controller or the development board (such as the LED.) This project uses almost all available pins on the chosen ESP32 development board. + - The OneWire sensors I use for temperatures could work with all sensors on a single wire for data (hence the "OneWire" name.) You are familiar with the slight inconvenience this poses if you have used one of the various fermentation temperature controllers. You have to connect one sensor at a time and assign its use, or heat/cool one sensor at a time so that you can label it. Each sensor has an internal address that allows it to be assigned to a specific use or name; however, figuring out which one is a little cumbersome. I wanted a more straightforward method of one sensor per pin so that there is an explicit physical configuration without such addressing concerns. Because of this approach, I have reserved five controller pins for temperature sensors. + - The flow meters do not have any method of resolving a sensor. The data pin pulses as the flow is detected. On the controller, we use one pin per sensor to catch each pulse independent of the others. Therefore, I have reserved nine pins for flow meters. + - Temperature control means that there needs to be a method of turning on and off the cooling. One pin is used for this to control a relay. + - Solenoid control is a feature that exists in many of the previous keg display systems. Because of the keg lines' proximity, this device seemed like the appropriate place to put the solenoid control. We use one pin for this, intended to turn on or off all solenoids at once using a relay. Some of the pins available to us are not appropriate for all uses. Some pins will prevent the controller from booting if held high or low as it would be if connected to a sensor or flow meter. Some pins will be set high or low during the boot process regardless of what the program will do when it starts. Such a pin attached to the cooling relay may cause the refrigerator compressor to short-cycle. I do not doubt that some crafty person might look at this and devise a more glamorous approach. For instance, there are I2C boards that would extend the system's capabilities. My final criteria for this design is to have a simple, compact design, capable of providing a prescriptive path to success for the average DIYer. Taking a very simplistic, 1:1 approach to interfacing software to the physical world meets this goal. If you are one of those people who think you can do it better, you have my blessing to fork the project and do your best. + +[828]: https://www.adafruit.com/product/828 +[sf800]: http://www.swissflow.com/sf800.html +[yf-s401]: https://www.ebay.com/itm/YF-S401-Water-Flow-Sensor-Meter-Flowmeter-Coffee-Dispenser-Counter-0-3-6-L-min/282112630770 diff --git a/docs/requirements.txt b/docs/requirements.txt index 0e04b3dd..69726740 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,4 @@ -recommonmark +myst sphinx sphinx_bootstrap_theme sphinx_markdown_parser diff --git a/docs/sysassembly/index.rst b/docs/sysassembly/index.md similarity index 89% rename from docs/sysassembly/index.rst rename to docs/sysassembly/index.md index 9800c3e8..4f05f9dc 100644 --- a/docs/sysassembly/index.rst +++ b/docs/sysassembly/index.md @@ -1,48 +1,42 @@ -.. _assembly: +(assembly)= -System Assembly -################### +# System Assembly -As you have learned in the discussion on :ref:`planning your system `, Keg Cop is capable of a wide variety of configurations. Each has similar building blocks, and you may apply that methodology to a variety of applications. +As you have learned in the discussion on {ref}`planning your system `, Keg Cop is capable of a wide variety of configurations. Each has similar building blocks, and you may apply that methodology to a variety of applications. Described here are a system with two flow meters, a room temp sensor, a keg temp sensor, a chamber sensor, cooling control, and a solenoid. The main board is the centerpiece of the system. It hosts the controller and serves as a connection for the relay, sensors, and flow meters. -.. image:: system.png - :scale: 15% - :align: center - :alt: System Diagram +```{image} system.png +:align: center +:alt: System Diagram +:scale: 15% +``` -Power -********* +## Power You will power the system with a micro-USB cable plugged directly into the controller's USB port. -Flowmeters -************ +## Flowmeters In the diagram above, you can see a crucial feature of the system; a single Ethernet cable leads to one or more flowmeters. The first cable is from the main board to the first flowmeter. Using the Daisy Chain boards, the first connection is always Flowmeter #1. Any subsequent connections will be #2, #3, and so on up to six. -Temperature Sensors -******************** +## Temperature Sensors Temperature sensors are optional; however, we will use them in this exemplar configuration. -Room Temperature -================== +### Room Temperature The room temperature sensor is optional, and we use it for display/reference purposes only. If you choose to utilize a room-temperature sensor, you have a choice. Either solder a DS18B20 in a TO-92 package directly to the PCB or using a sensor pre-assembled on a lead. If you use a TO-92 package sensor, be sure to provide ventilation for the main board. The ESP32 chip will generate some heat and throw off the readings if you do not. -Chamber Temperature -====================== +### Chamber Temperature Keg Cop offers four optional chamber sensors; we will use two for this example. We will use a single Ethernet cable to connect the Sensor breakout board to the main board. One pre-wired DS18B20 sensor is used each on the Keg and the Upper sensor ports. -Relays -************ +## Relays This system will control both the cooling and solenoids. We will use two-channel 5VDC relay to provide this control. @@ -61,14 +55,12 @@ We will use the four-pin header to control the relays. Connect the four-pin head - IN2 on the relay to S on RELAY header - GND on the relay to G on RELAY header -Cooling -======== +### Cooling In this diagram, we use Relay #1 for cooling. This document is not sufficient to describe how to do high voltage wiring. If you are not familiar with this concept, please seek out a licensed and insured electrician. Generally, we use the is used to make or break the hot side of the high voltage electrical circuit. When used in this manner, run the hot leg to the COM1 terminal. Run the load side to the NO1 terminal. -Solenoid -========= +### Solenoid Solenoids come in a wide variety of configurations. I have designed this system to actuate a single relay to control one or more solenoids simultaneously. Power the solenoids with a separate, dedicated power supply of sufficient amperage and proper voltage for the relays you implement. Run them in parallel, through the COM2 and NO2 terminals on Relay #2. diff --git a/docs/todo.md b/docs/todo.md new file mode 100644 index 00000000..75ab1d3b --- /dev/null +++ b/docs/todo.md @@ -0,0 +1,7 @@ +(todo)= + +# Documentation TODOs + +```{eval-rst} +.. todolist:: +``` diff --git a/docs/todo.rst b/docs/todo.rst deleted file mode 100644 index 9461dc9c..00000000 --- a/docs/todo.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _todo: - -Documentation TODOs -################################ - -.. todolist:: diff --git a/docs/troubleshooting/index.rst b/docs/troubleshooting/index.md similarity index 55% rename from docs/troubleshooting/index.rst rename to docs/troubleshooting/index.md index 7f134aeb..9cd50eb1 100644 --- a/docs/troubleshooting/index.rst +++ b/docs/troubleshooting/index.md @@ -1,25 +1,24 @@ -.. _troubleshooting: +(troubleshooting)= -Troubleshooting -###################### +# Troubleshooting This section will grow over time. I will add things here representing items that more commonly trip people up. -.. _faq-mdns: +(faq-mdns)= -Backup and Restore -******************** +## Backup and Restore A vestigial UI has been created if you desire to back up or restore your configuration. You may find this by navigating to `http://{kegcopname}.local/edit` (or via the IP address.) -.. image:: filesystem_editor.png - :scale: 50% - :align: center - :alt: Filesystem Editor +```{image} filesystem_editor.png +:align: center +:alt: Filesystem Editor +:scale: 50% +``` -.. note:: - The username is ``admin`` and the password is ``p@ssword``. - +:::{note} +The username is `admin` and the password is `p@ssword`. +::: Here you can: @@ -37,17 +36,17 @@ If you upload a configuration file, you must immediately reset the controller vi If the JSON is incomplete, the system will revert to default settings. If there are extra fields, they will be overwritten. If the JSON is invalid, the application will write a new default configuration in its place. Be sure you check your JSON format before you upload. -Cannot open Keg Cop by Name -***************************** +## Cannot open Keg Cop by Name -- Windows requires `Bonjour Print Services for Windows `_ to be installed to find local devices by name. Technically, newer OS versions and patch levels have mDNS support; however, that is only for 64-bit applications. Most web browsers are 32-bit. -- If you are on Windows 10 and still have issues, see the article: `Disable Windows mDNS `_ -- On Windows, to check if mDNS is working properly (independent of connecting to the controller), you can use `Bonjour Browser `_ +- Windows requires [Bonjour Print Services for Windows](https://support.apple.com/kb/DL999?locale=en_US) to be installed to find local devices by name. Technically, newer OS versions and patch levels have mDNS support; however, that is only for 64-bit applications. Most web browsers are 32-bit. +- If you are on Windows 10 and still have issues, see the article: [Disable Windows mDNS](https://superuser.com/questions/1330027/how-to-enable-mdns-on-windows-10-build-17134) +- On Windows, to check if mDNS is working properly (independent of connecting to the controller), you can use [Bonjour Browser](https://hobbyistsoftware.com/bonjourbrowser) -.. image:: bonjour_browser.png - :scale: 50% - :align: center - :alt: Controller Settings +```{image} bonjour_browser.png +:align: center +:alt: Controller Settings +:scale: 50% +``` -- Android phones have had a questionable history of support for mDNS - likely because the technology was adopted early on by Apple and is heavily ingrained in the Apple ecosystem. Reportedly, under ChromeOS 80 the Chrome Browser *does* resolve mDNS names (.local). Under Android 10, it does not. There is an issue on the `Issue Tracker `_, which is an interesting mix of phanbois giving reasons why it should not be supported, and real users who want it. -- From an Android smartphone, you can use something like `Service Browser `_ to browse mDNS services on your local network. +- Android phones have had a questionable history of support for mDNS - likely because the technology was adopted early on by Apple and is heavily ingrained in the Apple ecosystem. Reportedly, under ChromeOS 80 the Chrome Browser *does* resolve mDNS names (.local). Under Android 10, it does not. There is an issue on the [Issue Tracker](https://issuetracker.google.com/issues/140786115), which is an interesting mix of phanbois giving reasons why it should not be supported, and real users who want it. +- From an Android smartphone, you can use something like [Service Browser](https://play.google.com/store/apps/details?id=com.druk.servicebrowser) to browse mDNS services on your local network.