

# The Remake #

**Roland on the Ropes** was released in 1984, and to celebrate its 40th anniversary, I decided to re-implement it—while also getting to grips with Unity along the way. It was the very first computer game I ever played, and while nostalgia is its main draw for me, I’ll admit that the game itself <a href="https://www.mobygames.com/game/14333/fred/reviews/cpc/" target="_blank">doesn’t have much to offer</a> by today’s standards. That said, here’s my port! If you’re curious, there’s some backstory below. All the sounds and graphics have been faithfully ripped from the original.

<iframe src="https://schlussdienst.net/html/roland-web/index.html" width="960" height="645" style="border: 0"></iframe>

For comparison, you can watch a video of the original <a href="https://www.youtube.com/embed/KdbpTjspczQ?si=4AZYcST4U-C-8Siz&t=45s" target="_blank">here</a>. Alternatively, you can play it in an emulator over <a href="https://archive.org/details/Roland_on_the_Ropes_1985_Indescomp_Amsoft" target="_blank">at archive.org</a>.

# My first computer #

I remember that day very vividly. My father came home with his brand-new [Amstrad CPC 6128](https://en.wikipedia.org/wiki/Amstrad_CPC) that he just bought, and I was absolutely thrilled! At just eight years old, I knew very little about computers, but I was curious, and it felt like the future had finally arrived.

“What’s up with you? You won’t be using it anyway, so what gives?” my dad said. A smart man, but in this case, he couldn’t have been more wrong. By Christmas the following year, I had my very own CPC, and my dad could finally reclaim his machine.

<figure>
    <img src="/images/christmas.jpeg" alt="Welcoming the new family member at christmas 1988" />
    <div class="caption">Welcoming the new family member at Christmas 1988</div>
</figure>

These machines were relatively bare bones and did not come with a real operating system. Instead, the CPC booted straight into the [BASIC](https://en.wikipedia.org/wiki/BASIC) programming language. Without at least some fundamental knowledge, all you’d ever see was the start screen. To play a game, you had to load it manually with the `RUN` command.

My dad, a teacher, used the CPC to program a geometry calculator for his math classes. I was amazed—it felt like magic! Naturally, I wanted to learn how to do it, too. Whenever my dad was outside working in the garden, I was allowed to use the computer. I’d run back and forth between the garden and the computer, asking questions like, “How do I make the computer count to 10?” or “How do I make my text red?” He patiently answered each one, and I’d sprint back to try it out, only to return moments later with the next question. For some reason, I also vividly remember nibbling on a cucumber while doing this. I always enjoyed eating.

The games I had back then were simple enough that writing something similar seemed almost within reach. Over time, I got better, though the games I played grew more sophisticated, too. Eventually, I developed a full RPG engine with 3D graphics and all the bells and whistles. By then, though, no one cared—everyone had moved on to playing DOOM on PCs. It was time for me to move on, too. But that’s another story.

# Roland, Amstrad's Mario

The very first games I played were some Roland games. Roland was intended to be Amstrad's mascot, and I've just learnt from Wikipedia, that 

<cite>
    Roland was a game character developed in 1984 by Alan Sugar, CEO of Amstrad, and Jose Luis Dominguez, a Spanish game designer.
</cite>

That came as a surprise because, unlike Mario, who has a consistent look across every game, Roland seems to reinvent himself in each title. It’s fair to say that Amstrad didn’t put much effort into making Roland a cohesive franchise mascot.

<figure>
    <div class="figure-strip">
        <img src="/images/rolands/indiana-roland.png" alt="Roland dressed up as Indiana Jones" />
        <img src="/images/rolands/roland-who.png" alt="Roland as Dr. Who" />
        <img src="/images/rolands/roland-square.png" alt="Roland is a white box" />
    </div>
    <div class="caption">
         Some of Roland’s many faces. In <b>Roland on the Ropes</b> he channels Indiana Jones, while <b>Roland in Space</b> has strong Dr. Who vibes. In <b>Roland goes Square Bashing</b> he's literally a white box. And what is square bashing anyway? Is that a normal thing to do in the UK?
    </div>
</figure>


# Roland on the Ropes #

Originally released in Spain as **Fred** by Indescomp, the game found a second life internationally under the name **Roland on the Ropes** on the Amstrad CPC. It was one of the early titles for the platform and remains notable for its technical ambition, even if the execution had its quirks.  At its core, the game is an Indiana Jones-themed maze-style adventure where players guide an intrepid explorer through a labyrinth of hazards, including bats, mummies, and other creatures.

What set Fred/Roland on the Ropes apart, particularly for its time, was the scrolling. While this may not seem groundbreaking today, it was a significant technical achievement on the Amstrad CPC. The CPC lacked dedicated hardware for sprite manipulation or tile-based scrolling, unlike its contemporaries like the Commodore 64 or ZX Spectrum. This meant that programmers had to rely on the Zilog Z80 CPU to manually redraw the screen frame by frame—a computationally expensive process that could easily overwhelm the modest 4 MHz processor.

Despite this, Fred managed to implement scrolling using some <a href="https://www.cpcwiki.eu/index.php/Programming:Hardware_scrolling_the_screen_using_the_CRTC" target="_blank">magic tricks</a>. The results weren't perfect—the screen flickered, and performance could struggle under load—but for players in the mid-1980s, it was an impressive feat that demonstrated the potential of the relatively new Amstrad CPC.

# The Legacy of Paco Menéndez # 

One of the game's developers, Paco Menéndez, would go on to achieve greater fame with <a href="https://www.mobygames.com/game/14113/la-abadia-del-crimen/" target="_blank">La Abadía del Crimen (1987)</a>. This game, inspired by Umberto Eco's novel **The Name of the Rose**, is considered a masterpiece of its era. It was one of the first to feature isometric 3D graphics on 8-bit machines, offering an atmospheric and richly detailed experience. Players assumed the role of a monk investigating a murder in a medieval monastery, navigating both the game's intricate plot and the daily routines of monastic life.

While Fred was a relatively straightforward action-adventure game, La Abadía del Crimen pushed the boundaries of what video games could achieve narratively and technically. Menéndez's work on these titles highlights his talent for extracting remarkable results from limited hardware, cementing his place in gaming history.

If you're interested in reliving these classics, **La Abadía del Crimen** has been lovingly remade and remains accessible across <a href="https://en.wikipedia.org/wiki/La_Abad%C3%ADa_del_Crimen#Legacy">various platforms</a>.

Roland on the Ropes - 40th anniversary Unity remake


I'll have to cook for ~30 people soon, and as everybody loves chili, I've decided to go with it. I've cooked it way I like it, and noted down the ingredients and quantities that I used. This helped me to scale up properly. 

So, why shouldn't I share that with the world? Guess I'll be the only one who ever reads this anyway 😂 So here we go...

Serves <input type="number" x-amount="6"> people.

# Ingredients #

 - <input type="number" x-amount="75" />g (<input type="number" x-amount="1" /> pack) minced veggie protein like (e.g. [dmBio Veggie Hack](https://www.dm.de/dmbio-veggie-hack-p4066447600612.html))

- <input type="number" x-amount="1" x-round="0.25"/> large onion
- <input type="number" x-amount="0.5" x-round="0.25"/> leeks
- <input type="number" x-amount="1" x-round="0.5" /> bell pepper
- <input type="number" x-amount="2" x-round="0.5" /> carrots
- <input type="number" x-amount="2" x-round="0.25" /> tsp cumin
- <input type="number" x-amount="3" x-round="0.25"/> tsp paprika
- <input type="number" x-amount="0.5" x-round="0.25" /> tsp cinnamon
- <input type="number" x-amount="3" x-round="0.5"/> tbsp sugar
- <input type="number" x-amount="3" x-round="0.5" /> tbsp soy sauce
- <input type="number" x-amount="75" /> tbsp tomato paste
- <input type="number" x-amount="690" /> ml sieved tomatoes
- <input type="number" x-amount="2" x-round="0.5" /> garlic cloves
- some dashes of lemon juice
- nutritional yeast or veggie stock
- <input class="large" type="number" x-amount="240" />g (<input type="number" x-amount="1" x-round="0.5" /> can) of white beans
- <input class="large" type="number" x-amount="240" />g (<input type="number" x-amount="1" x-round="0.5" /> can) of kidney beans
- <input class="large" type="number" x-amount="240" />g (<input type="number" x-amount="1" x-round="0.5" /> can) of sweet corn

# Instructions

 - Chop onions and leeks. Sweat with some oil in a pot.
 - Add the veggies and spices. Sweat some more.
 - Add tomato paste and sweat.
 - Add everything else: sieved tomatoes, soy sauce, lemon juice, garlic, beans and corn.

Recipe: Chili


Good vegan cheese is hard to come by. Store-bought stuff is usually sub-par and artificially flavoured, which is basically the same thing. There are some shops specialized in vegan cheese, but not anyone is lucky enough to have one close by. 

The chesse we'll prepare here is cashew-based, and the water-soaked cashews will be blended to a fine mash. If you don't have a mixer that operates in the 10k rpm ball park, then you will end up with small pieces. While that does not affect the taste at all, I prefer the creamy mouth-feel. That's also why I increase the fat level to match the one of milk-based camembert. Fat tastes awesome, don't judge me!

Also, I've 3D-printed my [cheese mat](/stl/camembert-mat.stl), [mould](/stl/camembert-mould.stl) and the [covers](/stl/camembert-cover.stl) ([FreeCAD](/stl/camembert-kit.FCStd)). The latter are nicely stackable when not in use, and the cheese mat is big enough for 3 camemberts. I've printed 2 of those, so I can flip the cheese easily by putting a second mat on top and turn everything over at once. 

PETG is usually food-safe, but you might want to check your filament. And if you want to skip this hassle: There are plenty of  shops that sell sets that include everything you need.

<figure>
    <img src="/images/camembert-kit.png" alt="3D models of a cover and a cheese mat" />
    <div class="caption">3D models of a cover and a cheese mat </div>
</figure>

# Ingredients

- <input type="number" x-amount="300">g cashews (dry, ~<span x-amount="450"></span>g soaked)
- <input type="number" x-amount="130">ml water
- <input type="number" x-amount="40">g coconut fat
- <input type="number" x-amount="2" x-precision="1" x-round="0.5">tbsp yeast flakes
- <input type="number" x-amount="3">ml transglutaminase
- <input type="number" x-amount="3" x-precision="1" x-round="0.5">measuring cups starter culture
- <input type="number" x-amount="3" x-precision="1" x-round="0.5">measuring cups penicillium candidum

# Steps

1. **Soak cashews**: Take <span x-amount="300"></span>g of cashews and soak them with boiling water. Let sit for a couple of hours (or over night).
2. **Prepare cashew mix**: Drain the cashews. Blend on max power along with
    - <span x-amount="130"></span>ml water
    - <span x-amount="40"></span>g coconut fat
    - <span x-amount="2" x-precision="1" x-round="0.5"></span> tbsp yeast flakes
3. **Cool down**: Blending might heat things up a little, and both the starter culture and penicillium candidum are sensitive to heat. So let it cool down.
4. **Magic 🪄**: Add
    - <span x-amount="3" x-precision="1" x-round="0.5"></span> measuring cups starter culture
    - <span x-amount="3" x-precision="1" x-round="0.5"></span> measuring cups penicillium candidum
    - <span x-amount="3" x-precision="1" x-round="0.5"></span>ml transglutaminase

    and mix it.
5. **Fermentation**: Set aside at room temperature and the fermentation do it's thing for a couple of hours (at least 4).
6. **Sterilise cheesecloths**: Boil the cheesecloths and wring them out. We want the good bacteria to win, so let's avoid competition!
7. **Form the cheese**: Place a cheesecloth over a mould, and fill it with the fermented cashew mass. Also now is the time to add green pepper, walnuts or herbs if you like. Cover it with the cheesecloth and move the cheese to the fridge for a day. Some people recommend to turn it over after half of the time, but I found this to be optional.
8. **Unwrap** your cheese and put it on a cheese mat. Cover it, but don't seal it air-tight. It wants to breathe a little!
9. **Turn the cheese over every third day** and repeat until it's ready. This takes 3-5 weeks, and the longer you wait, the more intense the taste gets.
10. **Enjoy** and share a pic on insta or whatever. You did it 🎉

How to: Camembert fermentation


Serves <input type="number" x-amount="4"> people or <input type="number" x-amount="3"> hungry ones.

# Ingredients #
 
 - <input type="number" x-amount="2" x-precision="1"/> onions
 - <input type="number" x-amount="6" /> cloves garlic
 - <input type="number" x-amount="5" /> cm of ginger
 - Chili as you like. Fresh, dryed, spicy, mild, everything goes.

 - <input type="number" x-amount="2" /> tbsp oil (e.g. linseed)
 - Spices: 
    - garam masala
    - cumin
    - coriander
    - curcuma
    - chili powder
    - sugar
    - pepper
    - salt
 - lime juice

 - <input type="number" x-amount="100" x-round="25" /> ml vegetable stock
 - <input type="number" x-amount="2" x-precision="1" /> cans of chunky tomatoes (~<span x-amount="800"></span> ml)
 - <input type="number" x-amount="2" x-precision="1" /> cans of chickpeas (~<span x-amount="480"></span> g)

 - <input type="number" x-amount="2" x-precision="1"> block of tofu (<span x-amount="400"></span> g)

# Instructions
 
 - Blend <span x-amount="2" x-precision="1" x-round="0.5"></span> onions, <span x-amount="6" ></span> cloves of garlic, <span x-amount="5"></span> cm of ginger and chili as you like.
 - Heat a pan with with the oil, transfer the blended mass to the pan and sweat it a little
 - Add the spices (<span x-amount="2" x-precision="1" x-round="0.5"></span> tbsp garam masala, <span x-amount="1" x-precision="1" x-round="0.5"></span> tbsp cumin, <span x-amount="2" x-precision="1" x-round="0.5"></span> tbsp sugar and <span x-amount="1" x-precision="1" x-round="0.5"></span> of coriander, curcuma, chili powder each)
 - add chickpeas, tomatoes and tofu
 - cook it unit it's good
 - season to taste with salt, pepper, lime juice
    
# Nutritional value

 - Per serving: 570 kcal, 24 g protein, 35g carbs
 - Total: <span x-amount="2280"></span> kcal, <span x-amount="96"></span> g protein, <span x-amount="140"></span> g carbs

Recipe: Chana Masala


When converting my van, I've integrated quite some electrical components. To cover their needs, I've bought a LiFePO4 battery with 2.5kWh.

The battery apparently goes by a couple of names: 

 - [Liontron LiFePO4 Smart Bluetooth BMS (12.8V, 200Ah)](https://greenakku.de/Batterien/Lithium-Batterien/12V-Lithium/LIONTRON-LiFePO4-12-8V-200Ah-LX-Smart-BMS-mit-Bluetooth::1964.html)
 - SolarFam Rechargeable Lithium Iron Phosphate Battery
 - and probably more.

This battery comes with an app that provides information about the current charge, the number of cycles, and so on. However, this app was crashing quite a lot, but as it is the only way of knowing the charge, I kept checking it often.

<figure>
    <img src="/images/van/liontron-app.jpg" class="screenshot" alt="Liontron's app for checking BMS data" />
    <div class="caption">Liontron's app for checking BMS data.</div>
</figure>

Update: As I just learnt, they've updated the app so it can connect to several batteries at the same time. This app may or may not be better, I don't know. But you can now have multiple batteries on a single dashboard.

# Decompile the APK # 

First, I had to get hold of the APK of the application. As it turned out, it was still present on my phone, so that was an easy one. Next I had to decompile it. But as I am not terribly familiar with recent Java development, I was not too keen on installing the tools required. So I've turned to an [online version](http://www.javadecompilers.com/apk), which absolutely did the trick.

Judging from the namespace, it was obvious that the BMS was manufactured by the chinese company Jiabaida, which apparently offers white label BMS and corresponding apps.

The decompiled code was quite readable. I've searched for function calls that relate to  [Bluetooth Low Energy](https://developer.android.com/guide/topics/connectivity/bluetooth/ble-overview), and quickly found the service IDs and message structures involved. However, there's quite a lot going on in the app, and I guess they just removed the UI elements they did not need for the Liontron app. There's e.g. a camera image viewer in it, stuff that handles GPS trackers, and so on.

# Functional prototype

If you happen to have a Liontron battery of your own and would like to connect to it: Here's some source code for you.

The code assumes the [`node-ble`](https://www.npmjs.com/package/node-ble) package to be installed, and it starts a state machine that opens the BLE connection and tries to keep it alive.

To start it, you need to provide the device ID of your battery as well as a callback that is executed once device data has been received. The device ID resembles a MAC adress and looks something like this: `12:34:56:78:9A:BC`.

To obtain the device ID, you could either use your mobile (I believe I've used the *LightBlue* app back in the day on my Android device), or use the [device scanning functions](https://www.npmjs.com/package/node-ble#step-1-get-adapter) of `node-ble` just as fine.

You can use the code as follows: 
```typescript
const myBms = new JiabaidaBms("12:34:56:78:9A:BC", (info) => {
    console.log(`Data received: current: ${info.current}A, voltage: ${info.voltage}V, remaining power: ${info.remainingPower}Ah, nominal power: ${info.nominalPower}Ah, cycles: ${info.cycles}`);
});
```

And without further ado, this is what drives my BMS integration. It's MIT licensed, please report bugs.

```typescript
import NodeBle, { createBluetooth } from "node-ble";

export type BmsData = {
    /**
     * Voltage
     */
    voltage: number;

    /**
     * Current in Amps
     */
    current: number;

    /**
     * Remaining power in Ah
     */
    remainingPower: number;

    /**
     * Nominal power in Ah
     */
    nominalPower: number;

    /**
     * Number of battery cycles
     */
    cycles: number;
}


export class JiabaidaBms {

    private adapter?: NodeBle.Adapter;
    private device?: NodeBle.Device;

    private destroyBt?: () => void;

    /**
     * The following UUIDs are apparently hard-coded in the BMS and the app
     */
    private static serviceUuid = "0000ff00-0000-1000-8000-00805f9b34fb";
    private static readCharacteristicUuid = "0000ff01-0000-1000-8000-00805f9b34fb";
    private static writeCharacteristicUuid = "0000ff02-0000-1000-8000-00805f9b34fb";

    private readCharacteristic?: NodeBle.GattCharacteristic;
    private writeCharacteristic?: NodeBle.GattCharacteristic;

    private isStarted = false;
    private timeout?: NodeJS.Timeout;

    private lastSuccessfulPoll: Date = new Date();

    constructor(private deviceAddress: string, private onDataReceived: async (date: BmsData) => void | undefined) {
        // bind methods. This is necessary because the methods are called from the event handlers.
        // If we don't bind them, the 'this' context will be lost and the methods will fail.
        // This is a common pattern in JavaScript.
        // I have to admit that it's a bit ugly, but it's the way it is.
        this.start = this.start.bind(this);
        this.destroy = this.destroy.bind(this);
        this.stateMachine = this.stateMachine.bind(this);

        // Kick off state machine
        queueMicrotask(async () => {
            await this.stateMachine();
        });
    }

    public async start() {
        try {
            const { bluetooth, destroy } = createBluetooth();
            this.adapter = await bluetooth.defaultAdapter()
            this.device = await this.adapter.waitDevice(this.deviceAddress)

            await this.device.connect();

            console.log(`Connected to ${this.deviceAddress}`);

            const gattServer = await this.device.gatt();
            const service = await gattServer.getPrimaryService(JiabaidaBms.serviceUuid);
            console.log(`Service: UUID: ${await service.getUUID()}, Characteristics: ${(await service.characteristics()).join(", ")}`);

            this.readCharacteristic = await service.getCharacteristic(JiabaidaBms.readCharacteristicUuid);
            this.writeCharacteristic = await service.getCharacteristic(JiabaidaBms.writeCharacteristicUuid);

            // register callback that digests the BMS data we'll be polling
            this.readCharacteristic.on('valuechanged', buffer => {
                try {
                    // Check for the magic word
                    if (buffer[0] !== 0xdd || buffer[1] === 0x03)
                        return;

                    const info = this.decodeBaseInfo(buffer);
                    if (info !== undefined) {
                        // we received BMS data
                        if (this.onDataReceived)
                            await this.onDataReceived(info);

                        // Reset the watchdog
                        this.lastSuccessfulPoll = new Date();
                    }
                } catch (e) {
                    this.isStarted = false;
                    console.error(`Receiving BMS data failed: ${e.toString()}`);
                }
            });

            // start listening for notifications
            await this.readCharacteristic.startNotifications()

            // Periodically poll data from the BMS
            this.timeout = setInterval(async () => {
                if (!this.isStarted)
                    return;

                // dispatch a BMSBaseInfoCMDEntity 
                try {
                    if (this.writeCharacteristic) {
                        const buffer = Buffer.from([0xdd, 0xa5, 0x03, 0x00, 0xff, 0xfd, 0x77]);
                        await this.writeCharacteristic.writeValue(buffer);
                    }
                } catch (e) {
                    this.isStarted = false;
                    console.error(`Requesting BMS data failed: ${e.toString()}`);
                }
            }, 1000);

            this.isStarted = true;
            this.lastSuccessfulPoll = new Date();

            console.log("Successfully initialized BMS communication");
        } catch(e) {
            this.isStarted = false;
            await this.destroy();
            console.error(`Initializing BMS failed: ${e.toString()}`);
        }
    }

    /**
     * State machine that ensures the BMS communication is running. Issues it's
     * next run 5 seconds after the last one finished.
     */
    private async stateMachine() {
        try {
            if (!this.isStarted)
                await this.start();

            if (this.isStarted) {
                // Check if last communication was too long ago
                const delta = new Date().getTime() - this.lastSuccessfulPoll?.getTime();
                if (delta > 60000) {
                    console.error("Resetting BMS communication because of missing heartbeat");
                    await this.destroy();

                    // Reset this so the watchdog doesn't trigger again immediately
                    this.lastSuccessfulPoll = new Date();
                };
            }
        } catch (e) {
            console.error(`State machine failed: ${e.toString()}`);
        } finally {
            // Schedule next state machine run
            setTimeout(this.stateMachine, 5000);
        }
    }

    /**
     * Tear down the BMS communication
     */
    private async destroy() {
        try {
            if (this.timeout) {
                clearInterval(this.timeout);
                delete this.timeout;
            }

            if (this.readCharacteristic) {
                await this.readCharacteristic.stopNotifications();
                this.readCharacteristic.removeAllListeners();
                delete this.readCharacteristic;
            }

            if (this.writeCharacteristic) {
                this.writeCharacteristic.removeAllListeners();
                delete this.writeCharacteristic;
            }

            if (this.device) {
                this.device?.removeAllListeners();
                await this.device?.disconnect();
                delete this.device;
            }

            if (this.destroyBt) {
                await this.destroyBt();
                delete this.destroyBt;
            }

            console.log("BMS communication teared down");
        } catch (e) {
            console.error(`Tearing down BMS communication failed: ${e.toString()}`);
        } finally {
            this.isStarted = false;
        }
    }

    private decodeBaseInfo(buffer: Buffer) {
        if (buffer.length < 14)
            return;

        return {
            voltage: this.shortToFloat(buffer[4], buffer[5], 100),
            current: this.shortToFloat(buffer[6], buffer[7], 100),
            remainingPower: this.shortToFloat(buffer[8], buffer[9], 100),
            nominalPower: this.shortToFloat(buffer[10], buffer[11], 100),
            cycles: this.shortToFloat(buffer[12], buffer[13], 1),
        } as BmsData;
    }

    /**
     * Converts fixed-point 16-bit integer to float
     */
    private shortToFloat(high: number, low: number, scale = 100) {
        const value = ((high & 255) << 8) + (low & 255);
        if ((high >> 7) === 0)
            return value / scale;

        // negative value
        return (value - 0x10000) / scale;
    }
}
```

Reading from a Liontron LiFePO4 Smart Bluetooth BMS

As a software developer, it seems to be a natural urge to make everything controllable with an API. This time, I've built one for the main ventilation in my van. I installed a [Maxxair MAXXFAN deluxe](https://www.maxxair.com/products/fans/maxxfan-deluxe/), which comes with a remote. With that you can control all the cool features this fan provides:

 - works bidirectional: it can either suck air in or push it out
 - it has a motor that opens and closes the hatch
 - you can either set a speed (0-10) or a temperature setpoint

So I've connected an infrared receiver to an ESP8266 and recorded all commands. For a couple of minutes I've tried to reverse-engineer the protocol, but when I noticed that replaying the commands totally did the trick, I've called it a day.

So long story short, here's what you need to reproduce this:

 - an ESP8266. I've picked the WEMOS D1 Mini as usual.
 - an IR diode. I'm no electronics expert, so I went with the [Seeed Studio 101020026 IR-Sender](https://wiki.seeedstudio.com/Grove-Infrared_Emitter/). It has all the resistors in the right places.
<figure>
    <img src="/images/seeed-grove-ir-emitter.jpg" alt="Seeed Studio IR emitter" />
    <div class="caption">Seeed Studio Grove Infrared Emitter</div>
</figure>

 - Connect both the ESP and the diode with power (3.5V). I've added a DC-DC step down converter that reduces the fan's 12V down acccordingly.
 - Connect GPIO pin D2 with the TX pin of the diode
 - Open your fan, mount the diode directly in front of the receiver on the Maxxair PCB. You can actually mount everything inside the fan. There is space enough.
 
<figure>
    <img src="/images/maxxfan-ir-receiver-location.webp" alt="Location of the infrared receiver" />
    <div class="caption">Location of the infrared receiver</div>
</figure>

 - Compile and flash [this sketch](/sketches/MaxxairFanController.zip)
    - you'll need to install the `IRremoteESP8266` library
    - don't forget to set an SSID and WIFI password

Now navigate your browser to the IP address of the ESP, and you should see a primitive but functional web frontend with which you can control your fan.

At first I was a bit concerned about the reliability of this setup. However, it turned out to work actually super reliably - I've never seen a command that was lost in transit.

## Related work

 - Everlanders built something similar by simulating button presses using relays: https://www.youtube.com/watch?v=aS3BiYaEfiw
 

An API for Maxxair MAXXFAN Deluxe

As part of my effort to smart up my van, I've looked into how to make my heater controllable with an API. It is a **Autoterm Planar 2D** (now rebranded as **Autoterm Air 2D**) diesel heater, and it came with the **PU-27** control panel.

Heater and panel are connected with a 4-wired cable. The wires are colored red, blue, white and green. Which made me think: Red and blue is probably the power supply, as that's quite common for car components. And the rest might be RS232? They probably didn't make up their own protocol, because, after all, why should they?

A quick google research led me to [Grimoire's Blog](https://grimoire314.wordpress.com/2018/08/22/planar-diesel-heater-controller-reverse-engineering/), which supported my assumption. Grimoire also dug into the serial protocol used and explains how to build a proxy that sits between panel and heater. Everything received from the panel will be passed on to the heater, and vice versa. If you're interested in that, I suggest you head over to his blog and check it out. For the sake of completeness, I'll repeat the key points here as well:

The wiring is as follows:

<figure>
    <img src="/images/van/jst-sm-5-pin-plug.svg" alt="JST SM 5 pin schematics" />
    <div class="caption">Looking at the plug from the side where the cables go in.</div>
</figure>

 - 1: unused
 - 2: heater (TX) to panel (RX), 5V, green
 - 3: panel (TX) to heater (RX), 5V, white
 - 4: ground, blue
 - 5: +12V, red
 
The comm lines are operated at 5V, and using 3.3V signal levels won't work for the heater. So you either need to shift the logic levels (e.g. the `TXS0108E` should do the trick), or you use some serial to USB converter that can operate on 5V levels out of the box.

Also, all communication is initiated by the panel. The heater responds and never sends messages the panel did not ask for in the first place. After power up, the panel tries a couple of baud settings until it gets a valid response from the heater.

At first I was thinking about building the proxy with my weapon of choice, the ESP8266. But as I'm using a Raspberry Pi in my van anyway, I was fine with attaching two FTDI serial-to-USB converters, just as Grimoire did. That also shortened iteration cycles when I reverse engineered the protocol. Compiling and uploading sketches just takes more time than running some code on my laptop.

# The Proxy #

Before being able to analyze the protocol, I needed to build that proxy device that can be plugged between heater and panel. I wanted to be able to restore the original connection in case everything fails, so I've used the same connectors as Autoterm did (5-pin JST SM. Yes, 5 pin.).

<figure>
    <img class="box" src="/images/van/ftdi-enclosure-tinkercad.png" alt="The enclosure in Tinkercad">
    <div class="caption">The enclosure in Tinkercad.</div>
</figure>

I've also 3d printed a case that holds the two serial-USB adapters, provides space for the necessary wiring and can be wall-mounted next to the Raspberry. Nothing fancy, but does the job.

Print your own if you feel like it: [tinkercad](https://www.tinkercad.com/things/hlEVR1q5IRr) [stl](/van/heater-interface-enclosure.stl)

Once wired up, I've added some code that passes everything it receives on one serial port to the other, and vice versa. Now I could play with the heater and see which bytes changed.

<figure>
    <img class="box" src="/images/van/heater-proxy.jpg" alt="Image of the heater proxy" />
    <div class="caption">The finished heater proxy on a messy table.</div>
</figure>

# Protocol #

This is what I found out about the protocol. At the end I was able to replicate all functionality of the PU-27.

## Basic message structure

The basic message structure is as follows:

 - `0xAA`: Preamble. Each sentence starts with this.
 - Sender
     - `0x03`: Message originates from the panel
     - `0x04`: Response from the heater
 - Payload length in bytes
 - `0x00`, probably some padding
 - Command ID, see below
 - Payload: Depends on the command or response
 - Checksum: CRC16-MODBUS, calculated for the entire message. An online tool for calculating these can be found here: [https://www.modbustools.com/modbus_crc16.html](https://www.modbustools.com/modbus_crc16.html)

Messages are idempotent, so it does not make a difference if you send a command once or multiple times. In fact, the PU-27 controller usually repeats commands several times. 

During regular operation, the panel sends commands in a loop: 
 - `0x02`: Get settings
 - `0x11`: Report panel temperature
 - `0x0f`: Get status
 - `0x11`: Report panel temperature again

After that, this sequence repeats. Commands are emitted once every ~0.8s.

## `0x01`: Start heater

The payload is organized as follows:

| Offset | Content                                     |
| ------ | ------------------------------------------- |
| 0      | `0xFF 0xFF` Preamble                        |
| 2      | Mode, see below                             |
| 3      | Temperature setpoint in °C as a single byte |
| 4      | Ventilation: `0x01` = On, `0x02` = Off      |
| 5      | Power level, 0-9                            |


| Mode   | Description |
| ------ | ----------- |
| `0x01` | By T Heater |
| `0x02` | By T Panel  |
| `0x03` | By T Air    |
| `0x04` | By Power    |

Obviously, the temperature setpoint is only relevant for modes 1-3, and the power level for mode 4.

### Example:

Turn on the heater with ventilation and power level 3:
```
P >> aa 03 06 00 01 ff ff 04 10 01 03 2e af
H << aa 04 06 00 01 ff ff 04 10 01 03 f4 1e
```
## `0x02`: Get/Set settings

If this command is sent without payload, the heater responds with the current settings. Alternatively, the panel can send new settings. In that case, the payload is identical to the `0x01` (Start) command.

This command is also used to change the settings when the heater is running. 

The panel polls the settings periodically.

### Example

Set setpoint to 16°C, controlled by heater's sensor, with ventilation.
```
P >> aa 03 06 00 02 ff ff 01 10 01 03 e2 9c
H << aa 04 06 00 02 ff ff 01 10 01 03 38 2d
```

## `0x03`: Shutdown

Stops the heater. Stopping the heater can take a while, and you can check the status so see when that's finished.

This sequence seems to be always the same, regardless of the mode used.

### Example

```
C >> aa 03 00 00 03 5d 7c
H << aa 04 00 00 03 29 7d
```


## `0x04`: Initialization

Sent by the panel when it tries to establish a connection with the heater. Once it receives a valid reply, it sticks to the current connection settings. This command is never used again during regular operation.

### Example
```
C >> aa 03 00 00 04 9f 3d
H << aa 04 05 00 04 10 82 00 15 11 f9 82
```

## `0x11`: Report panel temperature

This one is used by the controller panel to report the temperature to the heater. This is relevant when the heater is operating in `By T Panel` mode.

Payload is just one byte (the temperature in °C), and the heater repeats whatever value the panel sends. This command is used during the regular polling cycle, and it is polled twice as often as e.g. the status request.

### Example

It's 10°C:

```
C >> aa 03 01 00 11 0a ba d1
H << aa 04 01 00 11 0a 7a 64
```

## `0x0F`: Status

The panel polls this one periodically. There is more in this response payload than I figured out, but this is what I know so far:

| Offset    | Content                                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 6         | Battery voltage * 10, e.g. 0x84 equals 13.2V                                                                                                                                                         |
| 9         | Operating mode, see below                                                                                                                                                                            |
| 14 and 16 | Ventilation power. During startup this value goes up to 0x96, and then decreases slowly down to 0x46 during regular operation (status 0x04). Also, this value seems to appear twice, god knows, why. |

| Operating Mode | Meaning       |
| -------------- | ------------- |
| `0x00`         | Heater off    |
| `0x01`         | Starting      |
| `0x04`         | Running       |
| `0x05`         | Shutting down |

### Example
Heater is running, Battery voltage is 13.2V, ventilation is at 109.

```
P >> aa 03 00 00 0f 58 7c
H << aa 04 13 00 0f 03 00 00 0a 7f 00 84 01 b2 04 00 37 37 00 6d 00 6d 00 64 c3 0a
```

# Implementation

I've written some typescript/node js code that does the interfacing. The software I'm running on the van is a mess to be honest, but I've cleaned up the relevant classes, [so you can grab them here](/heater.zip).

Some notes on the implementation:

 - You can totally inject commands, as long as forward all responses from the heater to the display. That way, the PU-27 is notified about e.g. changed setpoints or heater states. It nicely updates it's views.
 - When injecting commands, pretend to be the panel and use it's sender ID. This is fine.
 - I've added some code that tracks when the heater state was polled last by the panel. If it's disconnected, a timeout will be triggered and the code takes over polling.

# Installation / Deployment

The FT232RL serial-to-usb adapters work pretty much right out of the box on both Windows- and Linux systems. On my Raspberry PI they just popped up as e.g. `/dev/ttyUSB0`. However, there is no guarantee that one converter will have the same name after a reboot as it did before. So to be sure your setup keeps working you should assign an alias and work with that.

To do so, first check the port names the devices are connected to:
```
dmesg | grep ttyUSB

[    7.805124] usb 1-1.2: FTDI USB Serial Device converter now attached to ttyUSB0
[    7.813654] usb 1-1.3: FTDI USB Serial Device converter now attached to ttyUSB1
```

Then check the details for each of the devices found:

```
udevadm info --name=/dev/ttyUSB0 --attribute-walk
udevadm info --name=/dev/ttyUSB1 --attribute-walk
```

Armed with that information you can finally set up symlinks by creating a file `/etc/udev/rules.d/10-usb-serial.rules`. As I'm using identical converters, there is no way to distinguish them other than the USB ports they are attached to. Pick some attributes that describe each converter. I've picked then vendor- and product id, as well as the serial. But that's the same for both devices, so it could just as well be ignored.

My file looks like this:

```
SUBSYSTEM=="tty", KERNELS=="1-1.3", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", ATTRS{serial}=="A50285BI", SYMLINK+="ttyUSB_panel"
SUBSYSTEM=="tty", KERNELS=="1-1.2", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", ATTRS{serial}=="A50285BI", SYMLINK+="ttyUSB_heater"
```

`KERNELS` is the USB port as listed by `dmesg`, and the other attributes stem from the `udevadm` command.

After that we have symlinks `/dev/ttyUSB_panel` and `/dev/ttyUSB_heater`, which will map to the corresponding devices.

# UI #
With that information at hand, you should be able to easily integrate the heater into your system. I've built a nice UI for controlling and checking my heater. This is how it looks:

<figure>
    <img src="/images/van/ui.png" alt="Screenshot of the heater control UI" />
    <img src="/images/van/ui2.png" alt="Screenshot of the heater status UI" />
    <div class="caption">Heater controls and status</div>
</figure>

# References

## Parts
 - Raspberry PI 3
 - 2x FT232RL USB to serial adapter that supports 5V signal levels
 - JST SM 5 pin connectors (1x plug, 1x socket)
 - 2x Mini USB patch cables


 ## Links
  - [Grimoire's Blog](https://grimoire314.wordpress.com/2018/08/22/planar-diesel-heater-controller-reverse-engineering/). Go read it!
  - 3D printed enclosure: [tinkercad](https://www.tinkercad.com/things/hlEVR1q5IRr) [stl](/van/heater-interface-enclosure.stl)