Introducing the HyperText Coffee Pot

Please note this project has not been tested, and is likely not going to be tested, on a real coffee pot. My implementation relies on an entirely fictional digital coffee pot. No advice is given on how to implement this protocol with a real coffee pot.

I write mostly about coffee and technology on this blog. Indeed, this blog is an intersection of coffee and technology: I share my thoughts on coffee through the digital medium that is the web. As a coffee and technology enthusiast, I believe it is important for me to stay up to date on any standards that may operate at the intersection of these two interests. If I like coffee and technology, I will probably find a mix of the two just as exciting!

I was thinking about how I could mix coffee and technology. After some thought I remembered the Hyper Text Coffee Pot Control Protocol (HTCPCP), a protocol defined by the IETF that describes ways in which one can send commands to coffee machines. For coffee and technology enthusiasts such as myself, the protocol is a must read, especially if you find yourself interested in operating coffee pots remotely.

Thanks to the IETF, I had a new coffee and technology project idea: implement the coffee protocol they defined.

In this post, I am going to chat about my new HyperText Coffee Pot, available on my website at coffeepot.jamesg.blog.

Thinking About Digital Coffee Pot Control

Have you ever found yourself needing to control a coffee pot remotely? In case I ever find myself in this scenario, I decided to build a tool that would let me control a coffee pot remotely. Of course, I decided to follow the IETF protocol that defines how to control a coffee pot. That way, my coffee pot control program could interoperate with other coffee pots and similar programs.

The HTCPCP (which is an incredibly confusing name, and which I will now refer to as the "Coffee Protocol" from here on in) is not just a few web requests. It describes its own URI scheme, headers to accept, request body contents, and HTTP methods to accept.

Indeed, HTCPCP could not possibly operate within the standard methods described by HTTP such as GET and POST. Coffee pots have unique needs and the Coffee Protocol addresses them. The BREW method lets you instruct a coffee pot to brew coffee. The WHEN method ensures that your coffee pot or any extension built to pour milk into your freshly brewed coffee is not too eager and pours way too much milk into your brew.

Because the Coffee Protocol has its own URI scheme and HTTP methods, I decided to build an actual server instead of just using Python Flask or another web framework to accept Coffee Protocol requests.

Building the Coffee Protocol Server

My implementation of the Coffee Protocol consists of two parts:

1. A Coffee Protocol server powered by Python's socket library that accepts requests from the coffee:// URI scheme and all of the internationalized URIs defined in the specification.
2. A web server that lets you send commands to a coffee pot.

Because I do not trust myself to use this protocol on a real coffee pot, I decided to implement a digital coffee pot. The Coffee Protocol server acts like there is a real coffee pot but there is not in fact any coffee being brewed.

The Coffee Protocol server accepts these requests:

• BREW: Brew a coffee. If a coffee is already brewing, no new coffee will be scheduled to brew.
• POST: Same as BREW. However, POST is deprecated and support is only maintained for backwards compatability.
• WHEN: Stop pouring milk.
• GET: Return information about the coffee currently brewing.

The Coffee Protocol Server opens up a socket. If a request is sent to coffee://james (or any other valid URI with the coffee pot name "james"), the server will process the request. For a server to be processed, a valid HTTP request must be sent with any required headers as defined in the Coffee Protocol. I shall share an example of this in the next section when I talk about the web interface for my digital coffee pot.

I have not yet implemented the PROPFIND HTTP method so I have mapped it to GET for now. PROPFIND is described in the specification using this language:

If a cup of coffee is data, metadata about the brewed resource is discovered using the PROPFIND method [WEBDAV].

All coffee requests are saved in two JSON files:

• currently_brewing.json: Stores one record with information on the coffee that is currently brewing.
• past_coffees.json: Stores a log of all coffees brewed with the pot. This feature is useful to help monitor usage of your coffee pot and also to understand the rate at which you brew coffee.

If a GET request is made, the contents of the currently_brewing.json file are returned. Otherwise, an empty JSON object ("{}") is returned.

Building the Web Interface

I prefer to brew coffee without JSON requests. Hence, I built a web interface to make coffee requests. This web interface relays HTTP requests formatted in a specific way to the Coffee Protocol server. The web interface has four functions:

1. Provides information about the project.
2. Lets you interact with a coffee pot. You can request the coffee pot make a coffee, stop a coffee brewing any further, and stop the pouring of milk if milk is presently being poured.
3. Shows the status of any coffee currently brewing.
4. Shows the log of coffees made with the coffee pot.

Here is what the home page of the web interface looks like:

Let's say you have just woken up and want to make a brew. You can go to the web interface and specify the coffee pot you want to brew your coffee (in my case, James' Coffee Pot), and request any additions such as milk. My implementation adds a few alternative milks that are not defined in the original specification so that the habits of coffee drinkers today are reflected in my implementation.

After clicking "Brew Coffee", the digital coffee pot (read: completely not real coffee pot) will brew a coffee.

The web server translates your desired coffee characteristics into a Coffee Protocol request. The request will look something like this:

BREW coffee://james HTTP/1.1
Content-Type: application/coffee-pot-command
Accept-Additions: cream

start

As you can see, the BREW Method is sent to the coffee pot with the URI coffee://james. I specified that I wanted cream so the web interface has sent that request to the Coffee Protocol server using the Accept-Additions header. The post body is "start" which means I want to begin brewing a coffee. All requests must use the Content-Type application/coffee-pot-command to be considered valid by the Coffee Protocol server.

The Coffee Protocol server will then instruct the fictional coffee pot to brew your coffee.

Here is the page you see when you have requested the coffee pot to brew a coffee:

You can view the coffee being brewed, halt the brewing process, and stop pouring milk by using the web interface, too. You can only stop pouring milk when milk is actually being poured. The fictional coffee pot starts pouring milk five minutes after brewing began, as long as you indicated that you wanted milk in your coffee.

There is a timer that counts down so you can see how many minutes and seconds you need to wait to get your coffee fix (although one should wait for their coffee to cool down a bit after brewing before consuming the coffee).

Wrapping Up

The IETF protocol has made it easy for me to brew fictional cups of coffee without having to worry about what protocols and conventions I need to follow. I do think the protocol needs to be updated as it was last revised in 1998. I would advocate for an extension that lets one brew with an electric pour-over brewing device. This would require a lot of work as pour-over brewing entails a more complex procedure than a standard electric coffee pot may follow.

My curiosity for exploring coffee and technology has now been satisfied although I do still have improvements to make to my Coffee Protocol implementation. Requesting that milk should stop pouring requires further testing. You can go to coffeepot.jamesg.blog to view a live version of my Coffee Protocol implementation. You can brew coffees and see what coffees have been brewed by other website visitors.

My implementation is open sourced on GitHub so you can take a peek at the source code to learn how my server works.

Have you implemented the Coffee Protocol yourself? Have you tried my implementation and have feedback? Let me know by emailing me at readers@jamesg.blog.

Also posted on IndieNews.