Home

Awesome

JURA Protocol

C++ JURA protocol implementation for controlling a Jura coffee maker over a serial (UART) connection.

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 V1-Protocol any more I started this project to understand the new one and create a reference implementation for it.

Table of Contents

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

Example

The following example shows the interaction with a JURA coffee maker over XMPP. The complete implementation for this demo can be found here. Watch the video

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:

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).

NameCommandResponseDescription
UNKNOWNAN:01ok:-
Turn offAN:02ok:Turns off the coffee maker.
Erase EPROMAN:0AUNKNOWNUntested! Erases the EPROM. Do not use.
Test UCHIAN:0Cok:Test the UCHI steam plate.
Test Mode onAN:20ok:Turns on the test mode.
Test Mode offAN:21ok:Turns off the test mode.
UNKNOWNAN:40an:40-
UNKNOWNAN:AAok:-
Get Type of MachineTY:ty: (e.g. ty:EF532M V02.03)Returns the type of the machine.
UNKNOWNFA:01ok:-
(Button 1)FA:04ok:Simulates the button 1 press (left top).
(Button 2)FA:05ok:Simulates the button 2 press (left center).
(Button 3)FA:06ok:Simulates the button 3 press (left bottom).
(Button 4)FA:07ok:Simulates the button 4 press (right top).
(Button 5)FA:08ok:Simulates the button 5 press (right center).
(Button 6)FA:09ok:Simulates the button 6 press (right bottom).
Coffee Pump onFN:01ok:Turns on the coffee pump.
Coffee Pump offFN:02ok:Turns off the coffee pump.
Coffee Heater onFN:03ok:Turns on the coffee heater.
Coffee Heater offFN:04ok:Turns off the coffee heater.
Grinder onFN:07ok:Turns on the coffee grinder.
Grinder offFN:08ok:Turns off the coffee grinder.
Brew Group Something onFN:09ok:Turns something in relation to the brew group on.
Brew Group Something offFN:0Aok:Turns something in relation to the brew group off.
Coffee press onFN:0Bok:Turns on the coffee press.
Coffee press offFN:0Cok:Turns off the coffee press.
Init Brew GroupFN:0Dok:Initializes the brew group.
Brew Group to open PostionFN:0Eok:Moves the brew group into the "open" position.
Brew Group to grinding PostionFN:0Fok:Moves the brew group into the grinding position.
Brew Group to unknown Postion XYZFN:13ok:Moves the brew group into an currently unknown position.
Brew Group to unknown Postion XYZFN:1Bok:Moves the brew group into an currently unknown position.
Brew Group to throw out position?! Postion XYZFN:1Cok:Moves the brew group into the throw out position.
Brew Group to brewing PositionFN:22ok:Moves the brew group into the brewing position.
UNKNOWNFN:24ok:-
UNKNOWNFN:25ok:-
UNKNOWNFN:26ok:-
UNKNOWNFN:27ok:-
UNKNOWNFN:44ok:-
UNKNOWNFN:45ok:-
UNKNOWNFN:50ok:-
Turn offFN:51ok:Turns off the coffee maker.
UNKNOWNFN:54ok:-
UNKNOWNFN:55ok:-
UNKNOWNFN:60ok:-
UNKNOWNFN:61ok:-
UNKNOWNFN:62ok:-
UNKNOWNFN:63ok:-
UNKNOWNFN:64ok:-
UNKNOWNFN:65ok:-
UNKNOWNFN:66ok:-
UNKNOWNFN:67ok:-
UNKNOWNFN:70ok:-
UNKNOWNFN:71ok:-
UNKNOWNFN:72ok:-
UNKNOWNFN:73ok:-
UNKNOWNFN:80ok:-
UNKNOWNFN:81ok:-
UNKNOWNFN:88ok:-
UNKNOWNFN:89ok:-
Debug mode onFN:89ku:, Ku: pause ku:, Ku:, ...Enables the debug mode. Sends continuously ku:, Ku:, ... Once an action like opening the hot water valve accrues, outputs information like percentage done. To disable it again disconnect the coffee maker from power.
UNKNOWNFN:90ok:-
UNKNOWNFN:99ok:-

Coffee Brewing Sequence

Requirements

The following requirements are required to build this project.

Fedora

To install those dependencies on Fedora, run the following commands:

sudo dnf install -y gcc clang cmake python3 python3-pip
pip install --user conan==1.59.0 # conan 2.x.x is not supported right now

Raspberry Pi

To install those dependencies on a Raspberry Pi, running the Raspberry Pi OS, run the following commands:

sudo apt install -y cmake python3 python3-pip
pip3 install --user conan==1.59.0 # conan 2.x.x is not supported right now

For all the other requirements, head over here: https://github.com/Jutta-Proto/hardware-pi#raspberry-pi-os

Building

Run the following commands to build this project:

# Clone the repository:
git clone https://github.com/Jutta-Proto/protocol-cpp.git
# Switch into the newly cloned repository:
cd protocol-cpp
# Build the project:
mkdir build
cd build
cmake ..
cmake --build .

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