Awesome

ESP32 JURA

The work from this repository has been continued here: https://github.com/Jutta-Proto/protocol-cpp

This project aims to control newer JURA coffee maker models with an ESP32 and a new XMPP-IoT extension as reference implementation. Therefore we need to understand how the protocol for controlling JURA coffee makers works.

This work is based on the excellent work done by the people over at Protocol JURA. They were able to figure out the basic protocol used for communication with older JURA coffee makers.

Since newer models do not use this old V1Protocol any more I started this project to understand the new one.

Table of Contents

0. Example
1. Protocol
2. JURA Commands
3. Requirements
4. Building
5. Project Structure

Example

Protocol

General

There are several steps of obfuscation being done by the JURA coffee maker to prevent others from reading the bare protocol.

Connecting to an JURA coffee maker

To connect to an JURA coffee maker we are using a 5V UART signal with the following configuration:

• Baud Rate: 9600
• Data Bits: 8
• Parity: Disabled
• Stop Bits: 1
• Flow Control: Hardware flow control disabled
• RX Flow Control Threshold: 0

Deobfuscating

Once a connection has been established we can start sending and receiving data.
But all data send and received is obfuscated. The following description shows how to deobfuscate data received from the coffee maker.
To obfuscate data just follow the steps in reverse.

Step 0 The coffee maker always sends 4 "raw" byte per one byte of data with a break of 8ms in between each "raw" byte. This looks something like this:

01011011 <8ms break> 01011111 <8ms break> 01011111 <8ms break> 01011111 <8ms break>
01011111 <8ms break> 01111011 <8ms break> 01011111 <8ms break> 01011111 <8ms break>
01111011 <8ms break> 01111011 <8ms break> 01111111 <8ms break> 01011011 <8ms break>
01011111 <8ms break> 01111111 <8ms break> 01011011 <8ms break> 01011011 <8ms break>
01111011 <8ms break> 01111011 <8ms break> 01011011 <8ms break> 01011011 <8ms break>

Each line corresponds to one actual data byte.

Step 1
Each of our 4 "raw" bytes (each line) contains only 2 bits of our resulting data bit.
Bit 2 and 5.
All other bits (except 0) are set to 1.

0b01011011
    ^  ^
  DB1  DB2

DB1 and DB2 are our actual data bits here. We have to combine alle 8 (of our 4 "raw" bytes) into a single data byte.

Examples:

const std::array<uint8_t, 4> encData{0b01011011, 0b01011111, 0b01011111, 0b01011111};

// Bit mask for the 2. bit from the left:
constexpr uint8_t B2_MASK = (0b10000000 >> 2);

// Bit mask for the 5. bit from the left:
constexpr uint8_t B5_MASK = (0b10000000 >> 5);

uint8_t decData = 0;
decData |= (encData[0] & B2_MASK) << 2;
decData |= (encData[0] & B5_MASK) << 4;
decData |= (encData[1] & B2_MASK);
decData |= (encData[1] & B5_MASK) << 2;
decData |= (encData[2] & B2_MASK) >> 2;
decData |= (encData[2] & B5_MASK);
decData |= (encData[3] & B2_MASK) >> 4;
decData |= (encData[3] & B5_MASK) >> 2; // 0b00010101

Input            -> Output
0 0 0 1  0 1 0 1 -> 0 1 0 1  0 0 0 1
0 1 1 0  0 1 0 1 -> 0 1 0 1  0 1 1 0
1 0 1 0  1 1 0 0 -> 1 1 0 0  1 0 1 0
0 1 1 1  0 0 0 0 -> 0 0 0 0  0 1 1 1
1 0 1 0  0 0 0 0 -> 0 0 0 0  1 0 1 0

Step 2
In this step we switch both nibbles (4 bit) of each byte. Examples: 1100 1100 -> 0011 0011

uint8_t in = 0b00010101;
uint8_t out = ((in & 0xF0) >> 4) | ((in & 0x0F) << 4); // 0b01010001

Input                                                                               -> Output
01011011 <8ms break> 01011111 <8ms break> 01011111 <8ms break> 01011111 <8ms break> -> 0 1 0 1  0 0 0 1
01011111 <8ms break> 01111011 <8ms break> 01011111 <8ms break> 01011111 <8ms break> -> 0 1 0 1  0 1 1 0
01111011 <8ms break> 01111011 <8ms break> 01111111 <8ms break> 01011011 <8ms break> -> 1 1 0 0  1 0 1 0
01011111 <8ms break> 01111111 <8ms break> 01011011 <8ms break> 01011011 <8ms break> -> 0 0 0 0  0 1 1 1
01111011 <8ms break> 01111011 <8ms break> 01011011 <8ms break> 01011011 <8ms break> -> 0 0 0 0  1 0 1 0

Step 3
A last time we have to shift all bits in our byte around. Here we have to split up our byte into two nibbles (4 bit) and switch two bits each.
Examples: 1100 1100 -> 0011 0011

uint8_t in = 0b01010001;
uint8_t out = ((in & 0xC0) >> 2) | ((in & 0x30) << 2) | ((in & 0x0C) >> 2) | ((in & 0x03) << 2); // 0b01010100

Input            -> Output           -> Output_Hex Output_Dec Output_Char
0 1 0 1  0 0 0 1 -> 0 1 0 1  0 1 0 0 -> 54	84	T 
0 1 0 1  0 1 1 0 -> 0 1 0 1  1 0 0 1 -> 59	89	Y 
1 1 0 0  1 0 1 0 -> 0 0 1 1  1 0 1 0 -> 3A	58	:
0 0 0 0  0 1 1 1 -> 0 0 0 0  1 1 0 1 -> 0d	13	'\r'
0 0 0 0  1 0 1 0 -> 0 0 0 0  1 0 1 0 -> 0a	10	'\n'

Which results in the message TY:\r\n.

JURA Commands

Every message/command send from or to the coffee maker has to end with \r\n to be valid. For simplicity reasons we omit the \r\n from all of the following messages and examples.

Command Structure

In general for every valid command a response will be send from the coffee maker. The actual command is always uppercase (e.g. TY:) and the response send back is lowercase (ty:EF532M V02.03).

Available Commands

The following list of commands has been tested on an Jura E6 2019 platin (15326).

Coffee Brewing Sequence

• FN:07 # Grind on
• Sleep 3 seconds # Determines how strong the coffee will be
• FN:08 # Grind off
• FN:22 # Brew group to brewing position
• FN:0B # Coffee press on
• Sleep 0.5 seconds # Compress the coffee
• FN:0C # Coffee press off
• FN:03 # Turn on the coffee water heater
• FN:01 # Coffee water pump on
• Sleep 2 seconds # Initial amount of water
• FN:02 # Coffee water pump off
• FN:04 # Turn off the coffee water heater
• Sleep 2 seconds # Allow the water to run everywhere
• FN:03 # Turn on the coffee water heater
• FN:01 # Coffee water pump on
• Sleep 40 seconds # 40 seconds of water result in 200 ml of coffee
• FN:02 # Coffee water pump off
• FN:04 # Turn off the coffee water heater
• FN:0D # Reset the brew group and throw out the old coffee grain

Requirements

This project builds on top the excellent Espressif IoT Development Framework. Follow this installation guide and install version 4.0.1 of the framework on your computer.

Building

Step 0: Setup

# Clone the repository:
git clone https://github.com/COM8/esp32-jura.git
# Switch into the newly cloned repository:
cd esp32-jura
# Initialize the repository.
# This call will download further repositories and moves them to their appropriate place.
./init.sh

Step 1: Credentials.hpp

To be able to build the project you have to create the following file: ``
Paste the following content in this newly created file:

#pragma once

#include <string>

//---------------------------------------------------------------------------
namespace esp32jura {
//---------------------------------------------------------------------------
/**
 * This file contains credentials for debugging the XMPP and WIFI connection,
 * without having to go through the usual setup procedure.
 * To apply these settings uncomment the "initWithDummyValues()" call in the "Esp32Jura.cpp" file.
 *
 * !!NEVER COMMIT THIS FILE!!
 **/
const std::string SSID = "Your WIFI SSID";
const std::string PASSWORD = "Your WIFI Password";
const std::string JID = "JID of this device";
const std::string JID_PASSWORD = "Password for the JID of this device";
const std::string JID_SENDER = "The owner JID of this device";
//---------------------------------------------------------------------------
}  // namespace esp32jura
//---------------------------------------------------------------------------

This file contains debug and testing credentials for deploying the application on an esp32 without having to go through the usual setup procedure.

Step 3: Build

You can build the project with the following command:

cd esp32
idf.py build

Step 4: Flash

To flash the application on an ESP32 run the following commands:

cd esp32
idf.py -p /dev/ttyUSB0 flash

Replace /dev/ttyUSB0 with the port, where you plugged your ESP32 in to.

It might be required, that you add your current user to the dialout group.
For this run the following command and reboot your pc afterwards.

sudo adduser "$USER" dialout

Project Structure

.
├── esp32 # ESP IDF project
│   ├── ...
│   ├── CMakeLists.txt # Root CMake file
│   └── main # Source Code
│       ├── ...
│       ├── Esp32Jura.cpp # Main entry point
│       └── CMakeLists.txt
├── ...
├── init.sh # Initializes the project
├── LICENSE
├── protocol # Snoops of the JURA communication with a Smart Connect [1]
│   └── ...
└── README.md

[1]: https://uk.jura.com/en/homeproducts/accessories/SmartConnect-Main-72167