BeerBoi - Code

This section describes the code, how to upload the code to the ESP-12, and how to configure and calibrate the BeerBoi.

Set Up

For writing and deploying the code, I use:

The Arduino IDE is used for compiling the code and uploading it to the ESP-12. It's decent for what it does, but it isn't the best code editor by a long way. It does have an option to use an external editor (File - Preferences - check "Use external editor"), so I set that and use the excellent jEdit for actual coding (disclaimer, maybe? I've been contributing to jEdit for years and am a project admin). The Arduino IDE provides a serial monitor, which is good for watching messages from BeerBoi as it runs. Of course, you don't have to use these tools, the Arduino IDE by itself is enough.

Since this project is using an ESP8266 based board, you'll need to add an additional URL to the Arduino Board Manager. Start up the Arduino IDE, then go to File - Preferences, then enter this line in the "Additional Boards Manager. URLs:" box:

http://arduino.esp8266.com/stable/package_esp8266com_index.json

This will put the appropriate board definitions in the "Tools" menu. Select the appropriate board, in my case, I've got the "LOLIN (WEMOS) D1 mini (clone)" selected, since that is what I have. Any of the ESP boards should be able to run this code, just be sure to pick the one you actually have.

The project source code is arranged like this: 

beerboi
|- beerboi.fzz                (fritzing file for the beerboi circuit)
\- arduino libraries
   \- ArduinoJson             (json library for reading and writing the configuration files)
   \- HX711-master            (library for the weight scale)
   \- NTPClient               (library to connect to an NTP server for the current time)
   \- WiFiManager             (ESP8266 wifi connection manager)
\- src
   |- beerboi.ino             (the Arduino sketch for the boi)
   \- data                    (web pages and images for beerboi.local)
      |- about.html           (an about page, some info about BeerBoi)
      |- calibration.html     (web page to assist in calibrating a boi)
      |- configuration.html   (web page for how often to read the gravity, time zone for reports, etc)
      |- d3.min.js            (javascript to parse the boi data files for the chart)
      |- favicon.ico          (cute icon, looks like BB)
      |- index.html           (home page to read the gravity)
      |- style.css            (style sheet for the web pages)
\- sf                         (web pages and images for beerboi.org)
   \- images                  (images for beerboi.org)
   |- about.html
   |- assembly.html
   |- bootstrap.min.css       (stored here so the ESP-12F doesn't have to serve it)
   |- chart.js                (stored here so the ESP-12F doesn't have to serve it)
   |- code.html
   |- d3.v7.min.js            (stored here so the ESP-12F doesn't have to serve it)
   |- faq.html
   |- favicon.ico
   |- index.html
   |- parts.html
   |- setup.html
   |- style.css

bootstrap.min.css is a style sheet that works nicely for big and little browser screens.
chart.js and d3.v7.min.js are javascript files that are used by the index.html page served from the ESP-12F. I'm putting them on beerboi.org so that the ESP-12F doesn't have to serve them. The ESP-12F is a low power device and isn't very speedy, so having the browser pull these files from beerboi.org is much faster than letting the ESP serve them.

Everything in the src and data folders gets uploaded to the ESP-12.

Here is a direct link to beerboi.ino. It's heavily commented, so it should be pretty easy to understand.

To upload the code:

  1. Connect the ESP-12 to your computer with a USB cable.
  2. In Arduino IDE, under Tools menu, select the ESP-12 board, select the USB port, and make sure the flash size is set to 4 MB (FS:2MB OTA:~1019KB)
  3. Connect a jumper wire from pin D3 (GPIO0) to ground.
  4. Hit the upload button, wait until the upload is complete.
  5. Disconnect the jumper wire from pin D3 to ground.
  6. Hit the reset button on the ESP-12F

To upload the data directory:

To upload all the files in the 'data' directory, you'll first need to install the ESP8266 LittleFS Filesystem Uploader plugin into the Arduino IDE. See https://github.com/earlephilhower/arduino-esp8266littlefs-plugin for installation and usage details. After you've uploaded the code (see above):
  1. Connect the ESP-12 to your computer with a USB cable.
  2. Turn off the serial monitor if it is on.
  3. Connect a jumper wire from pin D3 (GPIO0) to ground.
  4. On the 'Tools' menu, choose 'ESP8266 LittleFS Data Upload', wait for the upload to complete.
  5. Disconnect the jumper wire from pin D3 to ground.
  6. Hit the reset button on the ESP-12F

The 'ESP8266 LittleFS Data Upload" will look for a 'data' directory in the same folder as the .ino file, and upload the contents of that folder to the ESP-12F. Really what it does is make a binary file system image on the Arduino IDE side, then uploads that image to the ESP-12 flash memory, which overwrites anything you previously had there, so you'll have to redo your configurations afterwards. You can create a default configuration by creating a file named "configuration.json" in your 'data' directory like this:

{
    "wifiSSID": "your_network_name",
    "wifiPassword": "your_network_password",
    "readFrequency": "60",
    "timeZone": "-6",
    "timeServer": "your_router_IP_address",
    "fsPercent": "85",
    "calibrationFactor": "1920",
    "boiWeight": "200.00",
    "m": "0.00900"
}


The values for the configuration file can be found by clicking the link on the Configuration page, or by going to http://beerboi.local/configuration.json. Now when you upload the data directory, you'll already have a configuration file with the proper values. You can see your current configuration file at http://beerboi.local/configuration.json.

Uploading over wifi:

BeerBoi supports over-the-air (OTA) updates. Once you've uploaded the beerboi.ino file to your ESP-12, you can then disconnect the USB cable and upload changes over the air. To create the .bin files for OTA update:
  1. Unplug the usb cable so there is no serial port connected
  2. Sketch, Export compiled binary, or hit the "Verify" button, or even the "Upload" button. All of these will compile the code.
  3. When compilation is complete, you should see a line like this in the compiler output:
    Creating BIN file "/tmp/arduino_build_XXXXXX/beerboi.ino.bin" (... lots more on that line)
    This line is up about 20 lines from the end. XXXXXX is a 6 digit number. This is the binary for the firmware.
  4. Tools, ESP8266 LittleFS Data Upload.
  5. This usually fails quickly, but the file has been created. Look for a line like this:
    [LittleFS] upload  : /tmp/arduino_build_XXXXXX/beerboi.mklittlefs.bin
    This is the binary for the file system. XXXXXX is the same 6 digit number.
  6. Point your browser at beerboi.local. Use the "Update firmware" button on the configuration page to upload the .bin files to the BeerBoi. The BeerBoi will reboot after each file is uploaded.

Libraries


I'm using these libraries in Arduino IDE. Some are installed via the Tools - Manage Libraries menu item, some are things I found on the internet, but are included in the svn repository for this project.

Libraries in SVN:

Libraries in library manager:

For the libraries that are in SVN, copy the complete folders to your Arduino libraries folder.

All of the code is in the BeerBoi project at SourceForge. You can get a copy of the code by going to https://sourceforge.net/p/beerboi/code/HEAD/tree/trunk/ and clicking the "Download Snapshot" link.