sw configuration

BeanBot’s configuation is done by editing a text file written in YAML (YAML Ain’t a Markup Language); the configuration file that is included has a lot of comments that try to describe what each option does, and I’ll use that as the example to go into more depth about the configuration.

The BeanBot Configuration File Described

The BeanBot configuration file is called, by default, scaleConfig.yaml, but using the --config option to scale.py you can specify the name of the configuration file you want to use.

The configuration file has three sections: configuration for the Raspberry Pi (raspberryPiConfig) that contains everything that BeanBot needs to run and make plots at Plot.ly; configuration for sending email (emailConfiguration) via either the local system or GMail; and configuration for sending tweets (twitterConfiguration).

There are a set of defaults encoded in the scaleConfig.py but all of them are overridden by the configuration file.

The raspberryPiConfig section

The raspberryPiConfig section of the file has four main purposes:

describe the physical wiring to the Python program
set limits (for jitter in the resistor, the maximum change to accept, and when to send a low-bean alert, how frequently to read the scale, is debugging on or off)
find the credentials file so plots can be made at Plot.ly
configure updates and alerts (what channel, email and/or Twitter and/or …, how frequent are updates)

Physical wiring

The values describing the physical wiring are:

# This defines the analog-to-digital converter connections to the
# PiCobbler; the circuitry is documented at:
# http://acaird.github.io/computers/2015/01/07/raspberry-pi-fsr/

ADCtoCobbler:
    SPICLK : 18
    SPIMISO: 23
    SPIMOSI: 24
    SPICS  : 25


# Which port on the analog-to-digital converter is the force sensitive
# resistor attached to?

adcPortWithFSR: 0

This is one of the places where the indentation is important, the SPI values are a sub-set of the ADCtoCobbler value.

If you follow the wiring diagram in the Construction section, these are the correct values.

Limits

The limits that BeanBot knows about are tolerance, maxChange, getMoarBeansNow, debug, and checkTime.

tolerance: the force-sensitive resistor (FSR) is sensitive (if not precise), so it will “float” around some value and cause updates to Plot.ly with unnecessary frequency. Setting tolerance will keep the BeanBot from being too sensitive to the FSR. I’ve set this around 40, but you’ll have to experiment with your own FSR and particular set-up to find a value that works.
maxChange: a bean scale is no good if you can’t take the jar or bag off it to pour into your coffee grinder, but you don’t want BeanBot freaking out and sending alerts everytime you make coffee; this value is some big value that, if BeanBot sees, will just be ignored. The sign on this matters, the negative sign means it went down and that’s what BeanBot sees when you lift up your beans. If you have a big hopper or make giant pots of coffee, you might want to change this
getMoarBeansNow: this is the alert level; depending on what exactly is on your platform, you could set this at 0, but if you have a container for your beans you might set it at 300 or whatever your empty container reads. (This is where running BeanBot’s scale.py program in debug mode can help; you can see what it reports for each setting in your environment.
checkTime: this determines how often (in seconds) BeanBot checks the value from the platform/FSR/ADC combination. As far as I know, there is no particular harm is keeping this pretty frequent (the default in scaleConfig.py is 2 seconds), but if you only make coffee once a day and don’t care if your graph is accurate in time, you could set it to check every hour (3600 seconds)
debug: if this is turned on, BeanBot’s scale.py will print things to the console of your Raspberry Pi and you can see what BeanBot is seeing, thinking, and doing. This can also be set with the command line option --debug to scale.py; the command line option overrides the value in the configuration file.

All of this together in YAML’s formatting with comments looks like:

# this will print things to the console; fun for watching, useful for
# debugging, but not needed for everyday use

debug: 1


# how much jitter should we tolerate?  The FSR is pretty chatty, so
# setting something reasonable here will keep too many status updates
# from happening; 9 is the about same as a 1% change, which seems
# reasonable

tolerance: 16


# this is about a 40% reduction from the 0--1024 range of the ADC's
# interpretation of the FSR; changes outside of this range are weird -
# probably someone took all of the coffee beans off the scale and we
# don't really want to report that

maxChange: -410


# What is the minimum FSR reading that will trigger notification?

getMoarBeansNow: 300


# how many seconds to wait between checking the 'scale'; this can
# probably be set at 300 (5 minutes) or 600 (10 minutes) or 1800 (30
# minutes), but setting it at a very small number (like 2) is fun and
# lets lots of updates happen so there is something to see as it runs

checkTime: 2

Plot.ly credentials

To make plots at Plot.ly you need an account and then you need to get an “API Key”. I’ll write more about this later, but for now you’re on your own.

Once you have those two things, put them into a file that you don’t share with people (or push to Github, or whatever). The format of that file is:

username: YourPlotlyUserName
apikey: YourPlotlyAPIkey

you can call the file whatever you want and tell BeanBot where to find it with the configuration option plotlyCredsFile, like:

# paths to credentials files

plotlyCredsFile:  ./plotlyCreds.sec

the default file name is ./plotlyCreds.sec.

Updates and Alerts

This looks like (more documentation coming soon):

# Low bean alerts should be sent on the following channels; these are
# limited to 'plotly', 'twitter', and 'email' in this version

alertChannels:
  - twitter

# Regardless of changes in the weight of the beans, update things (see
# the next block) on this frequency (in seconds); note that this is
# the number of seconds after scale.py was started; so if you start it
# at 9:30am one day, and set this to 86400, an update will take place
# every day at 9:30am until scale.py stops

updateTime: 86400

# The periodic updates (described above) should be sent on the
# following channels; these are limited to 'plotly', 'twitter', and
# 'email' in this version

updateChannels:
  - plotly
  - twitter

The twitterConfiguration section

The configuration section for Twitter comprises three parts: the path to the credentials file (twitterCredsFile); the message and hashtags for Twitter updates (twitterUpdateMessage and twitterUpdateHashtags); and the message and hashtags for Twitter low-bean alerts (twitterAlertMessage and twitterAlertHashtags).

Both lists of hashtags are YAML lists.

The contents of the file that is pointed to by twitterCredsFile are the Twitter consumer key and secret and the access token and secret. It looks like:

consumerKey:  vvmHoFoEpghTNe2lXd7xuDtHt
consumerSec:  8nbYc3UvLwKGYfPOU6DMMaNvFmmVI3JU4kn0mO0PwwEtuyMfKC
accessToken:  3013528785-s5qtZeIOMz2yFbUAxxn8wVtJmKhJrVYjUUkkL5k
accessSecret: VMbQlr5Rk2fOqmQGlCSK5IHSiuZ3b03fjMgprUjj9a6WL

(those aren’t actual keys, tokens, or secrets)

Altogether, the twitterConfiguration part of the configuration file might look like:

name: twitterConfiguration

twitterCredsFile: ./twitterCreds.sec

twitterUpdateMessage: "The bean inventory is {0}% at {1}."
twitterUpdateHashtags:
  - caen
  - beanbot
  - coffebeans

twitterAlertMessage: "OH NOES! The bean inventory dangerously low! ({0}% at {1})"
twitterAlertHashtags:
  - caen
  - beanbot
  - coffebeans
  - buymoarcoffeebeans
  - coffeeemergency

The messages have {0} and {1} in them; when scaleTwitter.py interprets the messages, {0} is the percentage of beans, {1} is the current date and time. You don’t have to use either of those, but note that Twitter will check for duplicate messages, so tweeting the same thing will result in an error from Twitter; adding the date/time stamp gets around that. Also, the combination of the Message and the Hashtags can’t be more than 140 characters long or it won’t be sent, so use with caution. The date string is always 20 characters long.

Whether or not these messages are used depends on the settings in the alertChannels and updateChannels.

The emailConfiguration section

The configuration section for email comprises four things: the mail server configuration; to and from addresses; a path to a credentials file containing authorization for GMail (or, with some code edits, any SMTP server that requires authentication, but come on, just make a GMail account); and the alert and update message information (the subject line and body contents).

The scaleEmail.py module looks for the string gmail in the smtpServer variable and if it is there, it authenticates using the information from the file pointed to by the gmailCredsFile.

The contents of the file that is pointed to by gmailCredsFile are GMail login and password (I suggest an application specific password):

[email protected]
YourApplicationSpecificPasswordOrActualPassword

(those aren’t an actual email address (probably) or password (even more probably))

The email[Alert|Update]Message uses the YAML multi-line variable construct; it’s weird, but check out the examples. The double blank lines get converted into one blank line on interpretation.

All together, this looks like:

name: emailConfiguration

smtpServer: smtp.gmail.com:587

gmailCredsFile: ./gmailCreds.sec

# Set the to and from addresses for the email; the fromAddr doesn't
# much matter, the toAddr determines who gets the warnings about a low
# bean situation

fromAddr:   [email protected]
toAddr:     [email protected]

emailAlertSubject: Low Bean Alert!
emailAlertMessage: >-
  This is your friendly BeanBot letting you know that it looks like
  you are low on beans.


  According to the bean weight sensor, you have {0}% of beans left.


  It is {1} and I hope you have time to get more beans soon.


  Happy coffeeing!

emailUpdateSubject: Coffee Bean Status
emailUpdateMessage: >-
  According to your weight sensor, you have {0}% of beans left.


  Hello, this is your friendly BeanBot updating you on your coffee
  bean status.  You have {0}% left, so there is no alert at this time,
  but I will let you know if you get low (based on your configured
  options).

  Happy coffeeing!

The subject variable is a simple text string. The message body variable can have multiple lines and it has two interpreted variables: {0} is the sensor percentage value; {1} is the current date. You don’t have to include either one of those in your message. If you do include them they don’t have to be in order, but you can’t include {1} without including {0}.