Using the ESP Web Tool in NextJS with your PlatformIO Project

Research and Desire has recently added a web flasher for the Open Source Sex Machine. But our website is built in NextJS, and the OSSM is compiled with PlatformIO, which isn't immediately compatible with the ESP Web Tool. So, how did we do it? Easily! And I'll show you how in this guide.

If you're not familiar with the OSSM, it's an open source PlatformIO project designed for the ESP32 micro controller - check it out here. Since this is a community project, we have developers, engineers and DIY sex toy makers of all kinds interacting with our work. So, it's essential that we remove as many barriers to entry as possible. For those who aren't developers by day, the hardest barrier to entry is flashing your OSSM device. Here's how we solved that problem in 45 minutes using ESP Web Tool, NextJS and our PlatformIO project.

1. Build Your Binary

In your PlatformIO project for ESP32, you'll need to build your project for ESP32. I'll assume that you already have a working ESP32 project, but for reference here's a stripped down version of our platformio.ini file:


[platformio]
default_envs = development

[env:development]
upload_speed = 921600
extends = common
platform = espressif32
board = esp32dev
framework = arduino

Then, we can create our binaries by running:

pio run

This will create a firmware.bin and partitions.bin file in the .pio/build/development directory. We'll need these files later.

2. Add ESP Web Tools to your NextJS Project

For this guide, we'll assume that you have a NextJS project using the app router. See here for more details on how to set that up: https://nextjs.org/docs/app

First, we'll need to install the ESP Web Tools package. Run the following command in your NextJS project:

yarn add esp-web-tools

At the time of this writing, ESP web tools also requires a very specific version of the styling package. If you're using yarn, ensure that version is installed by adding the following to your package.json:


{
  "resolutions": {
    "@material/web": "1.2.0"
  }
}

3. Create a clientside NextJS Component

Esp Web Tools must run on the client, so we'll create a client side component for this tool:


'use client';
import 'esp-web-tools';
import { useSearchParams } from 'next/navigation';

const ESPInstallButton = () => {

  return (
    <div className="mx-auto my-2 max-w-screen-2xl px-4">
      {
        <div
                dangerouslySetInnerHTML={{
                __html: `<esp-web-install-button manifest="/esp/manifest.json"/>`
          }}
        />
      }
    </div>
  );
};

export default ESPInstallButton;

Then, add this component to your server side pages as follows:


import React, { Suspense } from 'react';
import ESPInstallButton from 'ESPInstallButton';

export default async function Page() {
  return (
    <div>
      <Suspense>
        <ESPInstallButton/>
      </Suspense>
    </div>
  );
}

Now, when you navigate to this page, you should see the ESP Web Tools button. Clicking this button will open the ESP Web Tools interface. But, since we haven't specified the manifest.json file, this should fail to work.

4. Create a manifest.json file

Now, we need to create a manifest.json file in the public/esp directory of your NextJS project. This file should look like this:


{
  "name": "OSSM",
  "builds": [
    {
      "chipFamily": "ESP32",
      "improv": false,
      "parts": [
        {
          "path": "/esp/bootloader_dio_40m.bin",
          "offset": 4096
        },
        {
          "path": "/esp/partitions.bin",
          "offset": 32768
        },
        {
          "path": "/esp/boot_app0.bin",
          "offset": 57344
        },
        {
          "path": "/esp/firmware.bin",
          "offset": 65536
        }
      ]
    }
  ]
}

As you can see, this file references specific binaries, which must also be included in the public/esp directory of your NextJS project. You can copy two of these files (firmware.bin and partitions.bin) from the .pio/build/development directory of your PlatformIO project.

However, the other two you'll need to get from us. Here are some direct links to all the files we use:

5. Test it out!

Now, when you navigate to the page with the ESPInstallButton component, you should see the ESP Web Tools button. Click this button to open the ESP Web Tools interface. You should see the OSSM project listed in the dropdown. Select this project and click the install button. This will flash your ESP32 device with the OSSM firmware. Just promise us that if you're making some cool DIY sex toy that you'll show to off in the Kinky Makers discord.