Arduino Full Stack Tutorial

Deploying a React app on the ESP32

In this tutorial we are going to build a JavaScript single page app to blink a led.

The tutorial is targeted towards the ESP32 chip but a board with the ESP8266 will work as well. In fact any Arduino compatible board will do as long as it has the required program space. For example, you can use the Arduino Mega together with the Ethernet shield if that is what you have. I will describe the required changes for the different boards.

Of course in real life blinking a led definitely does not require a full blown front-end framework. However, the same workflow can be applied to a lot more complex use cases like this. Also the tutorial is more about the toolchain than it is about Arduino or React programming.

The ready project is hosted at Github. If you want to skip the tutorial and just try out the application first you can download the project from there and flash it to your microcontroller. Throughout the instructions I will also include links to the corresponding commits in the version control system. The links will look like this:

The tutorial is divided into 5 parts:

• 1. Development Environment
• 2. Project Setup
• 3. Back-end Development
• 4. Front-end Development
• 5. Building the Project

1. Development Environment

So let’s get started. There are few prerequisites that you need to follow this tutorial. First off you need a microcontroller development board. Because we are using the Arduino framework the same code is easy to port to multiple different platforms.

Most of the development boards come with an on board user configurable led but you may also connect your own. A relay module is another option. We just need something to toggle on and off.

Unless you already have the Arduino and Node.js development environments ready you will need to install:

• Node.js JavaScript runtime
• Arduino IDE
• Arduino ESP32 core or Arduino ESP8266 core

Make sure your node.js is newer than 8.10.0:

node -v

And that your npm is newer than 5.2:

npm -v

2. Project Setup

While the same workflow can be applied to any single page app framework we are going to use React. To get a head start we are going to create the project template with the create-react-app tool.

To generate the application boilerplate run:

npx create-react-app led-blink

Patiently wait while the script downloads half of the internet.

Running the command created us a new project directory called led-blink . Open the project in your favourite code editor. Our initial project structure now looks like this:

led-blink
├── README.md
  ├── node_modules
  ├── package.json
  ├── .gitignore
  ├── public
  │   ├── favicon.ico
  │   ├── index.html
  │   └── manifest.json
  └── src
      ├── App.css
      ├── App.js
      ├── App.test.js
      ├── index.css
      ├── index.js
      ├── logo.svg
      └── serviceWorker.js

While the create-react-app took care of our front-end boilerplate we still have nothing for the back-end that will be running on the microcontroller.

First move into the newly created project directory in the console window by running:

cd led-blink

Next we need to install some more tools to generate the back-end project:

npm install awot-scripts --save-dev

To generate the back-end boilerplate run:

npx awot-create BlinkServer

Or if you are using the Ethernet shield run:

npx awot-create BlinkServer Ethernet

The command created us a ready made Arduino webserver project under the directory BlinkServer. Open the project in the Arduino IDE. If you are planning to edit the Arduino code in your own editor instead of the official IDE, you will want to toggle on the Use external editor setting in the Arduino IDE preferences. Otherwise files that are open in the editor will not get updated if they are edited elsewhere.

Now the project structure looks like this:

led-blink
  ├── README.md
  ├── node_modules
  ├── package.json
  ├── .gitignore
  ├── BlinkServer
  │   ├── BlinkServer.ino
  │   ├── StaticFiles.h
  │   ├── aWOT.cpp
  │   └── aWOT.h
  ├── public
  └── src

3. Back-end Development

The HTTP API is going to be simple. We need to implement two HTTP handler functions. One for reading the current state of the led and one for updating it. For simplicity's sake we are going to use just the characters ‘0’ and ‘1’ to describe the state. Also set your wifi credentials to the WIFI_SSID and WIFI_PASSWORD definitions.

If you are using the ESP8266 chip we need to make one more modification. Renaming one import is all that is needed.

Hook up your development board, and verify that you have the the correct target board and serial port selected. Next open the serial console from Tools -> Serial Monitor in Arduino IDE and then upload the sketch to your microcontroller. When the microcontroller boots up and gets a connection it will print the local IP address. Copy it somewhere as we are going to need it later on.

Mine got the IP address 192.168.1.227.

Before moving on let's make sure our back-end works as expected.

To to turn the led off:

curl 'http://192.168.1.227/led' -X PUT --data-binary '0'

To to turn the led on:

curl 'http://192.168.1.227/led' -X PUT --data-binary '1'

4. Front-end Development

Now that the back-end is done, we are ready to start working with the user interface. Uploading the user interface files to the microcontroller board every time we make changes would be a way too slow development cycle. Luckily we can proxy all API requests to the microcontroller while we do local development. To forward the API requests to the microcontroller we need to configure the proxy setting in our package.json. Replace the arduino.ip with the address that was printed out in the Serial Monitor.

Because every cool javascript project uses a lot of libraries to do the most simple things we are going to add a react toggle button component as a project dependency.

npm install react-toggle-button --save

Spin up the development server unless it’s open already:

npm start

The script will take a while to load. Once it is done you should see something like this in your browser:

As instructed, open up the App.js and do the following modifications. .

Update: After writing this tutorial React has introduced function components and this is what the Create React App also uses in the generated code. You can either replace the whole App.js with the class based component or use the new function compoent style if you know how to do it. If you decide to use the class component just copy the App.js content from here:

Now toggling the button should also blink the led on the microcontroller.

5. Building the Project

We are almost ready to upload the app to the microcontroller, but first we need to build a minified version of it. To do this run:

npm run build

The command created us a new directory called build. This directory now contains the minified javascript and css files as well as other static files like images.

The next step is to serve these files with the microcontroller. Unless you have set the Use external editor setting in the Arduino IDE you will need to close the Arduino project at this point.

To convert the files in the build directory to a Arduino compatible format we need first add some configurations to the package.json.

Next run:

npm run dist

This command took the contents of build directory and embedded the data to the StaticFiles.h under the BlinkServer directory. To save some space the files were at the same time compressed with gzip. The script also generated the proper http headers for encoding, cache control, response length and content type. In real life you would most likely want to exclude this file from your version control system.

You can now upload your sketch. Point your browser to the device IP that is displayed when it boots up. With any luck, in a few hundred milliseconds you should see the same page as before, but now completely hosted on the microcontroller.

That's it!.