DEV Community: Timon van Spronsen

Introduction to hardware programming with DeviceScript

Timon van Spronsen — Thu, 25 Jan 2024 09:05:14 +0000

Hardware programming used to require you to learn C/C++. If you’re already familiar with JavaScript or TypeScript, you will be delighted to learn about DeviceScript, a TypeScript programming environment for microcontrollers. In this blogpost you’ll learn the basics of electronics and DeviceScript. We will create the “hello world” of programming: making an LED blink!

Hackerspace Pixelbar

This blogpost originates from a workshop organized at Hackerspace Pixelbar in Rotterdam, which was generously sponsored by No Fluff Jobs. A hackerspace is a physical space where people interested in science, technology or digital art (and many other areas) can meet and exchange ideas. Want to visit? We’re open on Wednesday evenings and Saturday afternoons. Feel free to connect with us on Discord or refer to our website for current opening hours. Additionally, we regularly organize workshops about JavaScript and web-related topics. Join our Meetup group to get notified of the next event!

Safety instructions

Keep these safety instructions in mind while working with electronics:

Don’t adjust wiring while a circuit is powered. In other words, plug out the USB cable connected to your computer.
Wash your hands after handling hardware. Some components may be lightly contaminated with toxic metals, so it’s good practice to wash your hands afterwards.

The setup

We’re going to need a few components to get going:

A Seeed Studio XIAO ESP32C3 with headers soldered on
A cable to connect the microcontroller to your computer (USB-C in our case)
A breadboard
A 5mm 2V LED – any LED will do, I recommend using a diffused LED
A 100Ω resistor – a higher value, e.g., 270Ω is fine too, the LED will just shine a little more dimly
A few jumper cables
Optionally: a button

Aside from hardware, here are the software requirements:

Node.js 18 or higher (LTS recommended)
Visual Studio Code
DeviceScript extension for Visual Studio Code

Before we start, it’s essential to learn a bit about the components we’re going to be using.

The breadboard

A breadboard is a way to build electronic circuits. The image below shows the front and the back of a breadboard with the adhesive backing removed. The top side is where we plug in our components and jumper wires. The backside demonstrates how everything is connected. The rows are connected horizontally, we call them terminal strips, they are not connected across the divider gap in the middle. The columns on the side (with the + and - above them) are called power rails, and are connected vertically.

The microcontroller

A microcontroller is a tiny computer on a single integrated circuit, common examples include Arduino and the ESP32 series. Microcontrollers usually contain several general purpose input/output pins (GPIO). These input/output pins allow us to connect components like LEDs. The pinout diagram below shows the pins present on the Seeed Studio XIAO ESP32C3, you can reference this diagram when you wire up the components.

The LED and resistor

An LED has two legs, we call them the anode (+) and the cathode (-). The anode leg is slightly longer. We use a resistor to limit the current that flows through the LED, if we were to omit a resistor, the LED could burn out. In my setup I’m using 2V 20mA LEDs, the specifications of your LED may differ slightly, not to worry, the specified resistor will likely be enough to keep your LED from burning out. The anode should be connected to the positive side of the circuit, while the cathode should be connected to the ground, the other way around won’t hurt the LED, but it won’t do anything either.

Wiring up the hardware

Let’s connect the components to the breadboard, you can follow the schema below. The bended leg of the LED in the breadboard schema below is the anode (the longer leg).

Let’s examine what we did. We connected the GND pin (ground) with a jumper wire to row 10, this connects the ground to the terminal strip on row 10 on the top side of the gap, meaning that the cathode of the LED is connected to the ground. The anode of the LED is connected with the resistor, which in turn is connected with pin D6.

Programming the hardware

Now onto the most fun part! First create a new folder to contain your project (e.g., blinky), open this folder in VS Code (File → Open Folder…). If you have the DeviceScript extension installed you should see a DeviceScript icon in the activity bar, click on it, then press “Create New Project” and follow the wizard.

Go back to the file explorer, open src/main.ts and replace the contents with the code below.

import { startLightBulb } from "@devicescript/servers";
import { pins } from "@dsboard/seeed_xiao_esp32c3";

const led = startLightBulb({ pin: pins.SCL_D5 });

setInterval(async () => {
  await led.toggle();
}, 1000);

A couple of things to note here. It’s important to import the correct pin definitions, as every board has different pins, or a different layout. I once made the mistake of importing the pin definitions for esp32c3_bare instead, wondering for an hour why my code didn’t work 😅. startLightBulb starts a client to interact with the LED that we connected, we have to give it the pin that’s driving the LED (D5). await led.toggle() will toggle the LED on and off, this is encapsulated in a setInterval which is triggered every 1000 ms (= 1 second).

Flashing the microcontroller

Before we can load our code on the microcontroller, we have to flash the DeviceScript firmware onto the microcontroller.

Connect the microcontroller to your computer with a USB cable.
Open the command palette in VS Code (Command+Shift+P on Mac, Ctrl+Shift+P on Windows and Linux), search for “flash”.
Select DeviceScript: Flash Firmware… and choose the appropriate device.

A terminal will open where you can track the progress, it might take a few seconds, once finished it should say “flash OK”. You can now connect the device.

Loading code onto the microcontroller

Once again, open the DeviceScript panel, but now click on “Connect Device”, then select serial, your device should now appear in the sidebar (1). Then click on the little chevron besides the debug button in the top-right corner (2) and select “DeviceScript: Run” from the context menu. The LED on your breadboard should now start blinking!

The result

Dimming an LED

Let’s make things slightly more exciting, we’ll make the LED fade. To achieve this we must add dimmable: true to startLightBulb, this will allow us to change the intensity of the LED with led.intensity.write(intensity), where intensity is some number between 0 and 1.

import { sleep } from "@devicescript/core";
import { startLightBulb } from "@devicescript/servers";
import { pins } from "@dsboard/seeed_xiao_esp32c3";

const led = startLightBulb({
  pin: pins.SCL_D5,
  dimmable: true,
});

const fadeInLevels = [0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1];
const fadeOutLevels = [1, 0.9, 0.8, 0.7, 0.6, 0.5, 0.4, 0.3, 0.2, 0.1, 0];

async function fade() {
  // Fade in
  for (const level of fadeInLevels) {
    await led.intensity.write(level);
    await sleep(50);
  } // Stay at peak brightness for a bit
  await sleep(500); // Fade out
  for (const level of fadeOutLevels) {
    await led.intensity.write(level);
    await sleep(50);
  }
}

while (true) {
  await fade();
  await sleep(200);
}

Next steps

This concludes the tutorial. Next up you could try wiring up a button to a digital pin and use it to toggle the LED, I’ll leave you with the schema below. If you have any questions, don’t hesitate to drop by Pixelbar hackerspace in Rotterdam. We also have a Discord community that you can join to ask questions.

Developing a Website with React, Feature Flags, Netlify and GitHub Actions

Timon van Spronsen — Fri, 19 Jul 2019 11:25:57 +0000

Please note: this post was written for GitHub Actions v1. GitHub Actions v2 has been released which deprecates the HCL syntax for workflows which renders some parts of this blog post unusable. To learn more about GitHub Actions v2, please refer to the documentation and the excellent posts by Edward Thomson.

In recent weeks I've helped develop a website for a very exciting project at Awkward called Coffee by Benjamin. Coffee by Benjamin is a coffee roasting kit that allows anyone to roast their coffee at home, this guarantees the freshness of the coffee. The project will launch on Kickstarter soon. If you'd like to keep notified about this project you can follow them on Instagram or visit the website.

This project is my last one at Awkward as I'll be taking up a new challenge at another company soon. Even though I won't be a part of the project going forward, I still want to share something about the way we've been developing and shipping the website by utilizing React, feature flags, Netlify, and GitHub Actions.

Problem statement

The website will launch in three separate phases outlined below. We're currently in phase 1 but we're nearing completion on phase 2. Meanwhile, we've already started development on phase 3.

Phase 1: a simple landing page where people can fill in their email address to get notified when the project launches.
Phase 2: a full-fletched website which contains more information about the project, a FAQ and a support form. This will launch together with the launch of the Kickstarter campaign.
Phase 3: integrate Shopify into the website to sell the product directly. This will launch after the project has been successfully funded and shipped.

Even though phase 3 won't launch till much later, we wanted to start development on this phase as soon as possible because it's the most complicated part of the website to build. This allows us to start testing the shop functionality long before it's launched and catch costly bugs from creeping into the website.

Now we could build phase 3 in a separate branch, but we'd have to constantly update and solve merge conflicts on this branch when we update the phase 2 website. This is especially hard because there are a lot of overlapping parts that we'll change in phase 3. Furthermore, this would result in having to merge a gigantic pull request when phase 3 launches which comes with the risk of bugs in existing functionality. Instead, we want to gradually merge functionality from phase 3 in the main branch without exposing it to the public. We also want the team to be able to check the progress on both phase 2 and phase 3. Finally, we'd like to completely exclude any code from phase 3 while phase 2 is live so that we don't ship any unnecessary code.

In the rest of the post I'll explain how we used a combination of feature flags, Netlify and GitHub Actions to achieve these goals.

The tray you'll get as part of the home roasting kit

Feature flags

The problem statement just screams for feature flags, which is exactly what we'll be using. Feature flags allow us to ship parts of phase 3 but don't actually show them to the public. Let's take a look at a definition of feature flags:

Release Toggles allow incomplete and un-tested codepaths to be shipped to production as latent code which may never be turned on.

— Feature Toggles, Pete Hodgson

The nice thing about feature flags is that it allows you to switch between new and old functionality with the flip of a switch. Usually you do this by wrapping new functionality in a condition like so:

function Header() {
  if (USE_NEW_FEATURE) {
    return <NewHeader />;
  }

  // feature flag is not enabled
  return <OldHeader />;
}

In code that's affected by a feature flag, you'll add new code without replacing the old code. This allows pull requests with new but overlapping functionality to be merged as they won't replace any existing functionality. Later when the feature flag is being phased out you can remove the conditions and remove any old code.

Let's see how we can implement this into our stack.

Feature Flags in Create React App

We can implement feature flags by using environment variables which Create React App supports out of the box. The benefits of using environment variables are that they're easy to use and they're compile-time constants, which means that code that is guarded by a condition that checks for the flag being enabled will be completely excluded from a build where the flag was disabled.

Environment variables in Create React App can be supplied in a .env file. The .env file will contain the default value to use and is checked into Git and will only be changed when phase 3 goes live.

.env:


REACT_APP_SHOPIFY_INTEGRATION_ENABLED=false

Now we can use the feature flag in App.js to conditionally render the shop routes. By conditionally rendering the shop routes using a compile-time constant, the code won't end up in the production bundle unless the flag is enabled and users won't be able to route to these pages. The code for the pages will still end up in the production bundle, more on that later.

src/App.js:

import React, { Suspense } from 'react';
// ... more imports hidden
import Home from 'pages/Home';
import Shop from 'pages/shop';
import Cart from 'pages/cart';
import ProductDetail from 'pages/product-detail';

const App = () => (
  <Router>
    <Switch>
      <Route exact path="/" component={Home} />
      <Route path="/faq" component={Faq} />
      <Route path="/support" component={Support} />
      {process.env.REACT_APP_SHOPIFY_INTEGRATION_ENABLED === 'true' && (
        <>
          <Route path="/shop" component={Shop} />
          <Route path="/cart" component={Cart} />
          <Route path="/product/:productId" component={ProductDetail} />
        </>
      )}
    </Switch>
  </Router>
);

ReactDOM.render(<App />, document.getElementById('root'));

Now that we've got the feature flag set up developers can add a .env.local (or any of the other supported .env files) which won't be checked into git.

.env.local:

REACT_APP_SHOPIFY_INTEGRATION_ENABLED=true

Configuring Netlify

Now only developers can see the Shopify integration by checking out locally and changing the environment variable in .env.local, what about other people that might want to review the site with a simple link? This is where Netlify comes in. Netlify allows developers to configure the build settings per branch and all branches will be deployed with a unique URL (separately from deploy previews), I'll let the Netlify documentation speak for itself:

Branch deploys are published to a URL which includes the branch name as a prefix. For example, if a branch is called staging, it will deploy to staging--yoursitename.netlify.com.

NOTE: You may have to manually set the branch deploys setting to deploy all branches, this is explained in the Netlify documentation.

We can add a branch in Git called shop-staging and configure netlify.toml to build this branch with the REACT_APP_SHOPIFY_INTEGRATION_ENABLED feature flag enabled.

netlify.toml:

[build]
  publish = "build"
  command = "npm run build"

[context."shop-staging"]
  command = "REACT_APP_SHOPIFY_INTEGRATION_ENABLED=true npm run build"

Prefixing the build command with REACT_APP_SHOPIFY_INTEGRATION_ENABLED=true will override the settings in .env. The site with the feature flag enabled will now be automatically deployed to shop-staging--yoursitename.netlify.com. We can now give this URL to testers and they'll be able to check out the progress on phase 3 and they can still check out the progress on phase 2 by visiting develop--yoursitename.netlify.com. You can also use this approach to enable the feature flag for deploy previews for certain pull requests.

There's still one problem though, the shop-staging branch will have to be to kept in sync with the main branch (in our case develop). Luckily, GitHub provides an extensive API which provides a way to do a fast-forward update for a branch, this allows us to keep the shop-staging branch in sync with the develop branch. All we have to do is provide it the ref we want to update (heads/shop-staging) and a commit SHA of the latest commit on the develop branch and then shop-staging will be in sync with the develop branch. Furthermore, we can automate this process by using GitHub Actions!

Creating a GitHub Action to keep branches in sync

GitHub actions, just like shell commands, are extremely composable. There's a lot you can accomplish by composing a few predefined actions. In this case we technically only need the Filter action and the cURL action. But I couldn't get the cURL action to accept a JSON body with an interpolated value, so we'll be creating our own.

There are two ways to create GitHub Actions, you can create a separate repository that contains the Action, this way other projects will be able to reuse the Action. But for something small that you won't reuse you can create an Action right inside of the repository where the rest of the code for your project lives.

We first create a folder .github, inside of it we create a folder called branch-sync-action. We must then create a Dockerfile, the contents are copied from the cURL action, we just change some of the labels. This Dockerfile ensures that we can use cURL which we'll use to do the HTTP call.

.github/branch-sync-action/Dockerfile

FROM debian:stable-slim

LABEL "com.github.actions.name"="Branch Sync"
LABEL "com.github.actions.description"=""
LABEL "com.github.actions.icon"="refresh-cw"
LABEL "com.github.actions.color"="white"

COPY entrypoint.sh /entrypoint.sh

RUN apt-get update && \
    apt-get install curl -y && \
    apt-get clean -y

ENTRYPOINT ["/entrypoint.sh"]

Next, we create an entrypoint.sh which is the script that will be executed when running the action.

.github/branch-sync-action/entrypoint.sh

#!/bin/sh

TARGET_BRANCH=$1

curl \
  -X PATCH \
  -H "Authorization: token $GITHUB_TOKEN" \
  -d "{\"sha\": \"$GITHUB_SHA\"}" \
  "https://api.github.com/repos/$GITHUB_REPOSITORY/git/refs/heads/$TARGET_BRANCH"

$1 stands for the first argument provided to the script. For clarity we give it the name TARGET_BRANCH.

Don't forget to provide execution permissions by doing chmod +x entrypoint.sh.

That's it for the action itself. Now we have to hook it up in a workflow:

.github/main.workflow

workflow "Sync shop-staging branch with develop" {
  on = "push"
  resolves = ["Sync Branch"]
}

action "Filter develop branch" {
  uses = "actions/bin/filter@master"
  args = "branch develop"
}

action "Sync Branch" {
  needs = ["Filter develop branch"]
  uses = "./.github/sync-branch-action"
  secrets = ["GITHUB_TOKEN"]
  args = ["shop-staging"]
}

In .github/main.workflow we define workflows for our project. Workflows decide which actions to run and when. In the workflow block we tell it when to run by defining the on attribute, in our case the workflow should run for every push event, we also define the actions it should execute (in parallel) by defining the resolves attribute.

Next, we define the filter action. GitHub will send a push event for every push to any branch, we want to add a filter so that we only sync the shop-staging branch when someone pushes to the develop branch, we're not interested in pushes to any other branch. In the uses parameter we point to the slug of the GitHub repository that provides this action and in this case the folder within this repository (filter). The @master part tells it to use the code that was published on the master branch.

Finally we add the action that syncs the shop-staging branch with the develop branch. It has the needs parameter defined which tells GitHub Actions that it should first run the filter action and only continue with Sync Branch if the filter action succeeds. Furthermore we define the uses parameter which will point to the folder containing the Dockerfile and entrypoint.sh which is used by GitHub Actions to run it. We also pass it the GITHUB_TOKEN as a secret which we need to make an authenticated HTTP call, GITHUB_TOKEN is a uniquely generated token for every project on GitHub. Lastly, we provide the arguments for entrypoint.sh which is the target branch it should sync to.

We'll end up with a flow looking like this:

It's important to note that the sync is one-way only. Everything that's pushed to develop will be fast-forwarded to shop-staging, if you're pushing to shop-staging nothing will happen, it will cause problems with future synchronization because updates can't be fast-forwarded anymore. You can solve this by enabling the force parameter in the cURL request or by resetting the shop-staging branch using git reset.

Lazy loading shop routes

A last problem we still have to tackle is excluding phase 3 related code from the bundle while phase 2 is live. We can tackle this by utilizing some new features released in React just last year: React.lazy and Suspense. The changes we have to make to our code are quite minimal, we have to change the way we're importing the shop pages by utilizing React.lazy and dynamic imports:

src/App.js:

import React, { Suspense } from 'react';
// ... more imports hidden
import Home from 'pages/Home';
const Shop = React.lazy(() => import('pages/shop'));
const Cart = React.lazy(() => import('pages/cart'));
const ProductDetail = React.lazy(() => import('pages/product-detail'));

const App = () => (
  <Suspense fallback={<div>Loading...</div>}>
    <Router>
      <Switch>
        <Route exact path="/" component={Home} />
        <Route path="/faq" component={Faq} />
        <Route path="/support" component={Support} />
        {process.env.REACT_APP_SHOPIFY_INTEGRATION_ENABLED === 'true' && (
          <>
            <Route path="/shop" component={Shop} />
            <Route path="/cart" component={Cart} />
            <Route path="/product/:productId" component={ProductDetail} />
          </>
        )}
      </Switch>
    </Router>
  </Suspense>
);

ReactDOM.render(<App />, document.getElementById('root'));

Now the shop pages will not end up in the main bundle, they will instead be lazily loaded when a user hits one of the shop routes. Which is impossible when the flag is not enabled. All of the routes are wrapped in a Suspense component which is responsible for showing a fallback state when visiting one of the lazily loaded routes as it still takes some time to download the bundle. If you'd like to know more about code-splitting (in React) I can recommend the excellent React documentation.

Demo

I created a simplified example of the code in this post which you can check out here: https://github.com/TimonVS/sync-branch-demo. You can clone it and push a commit to the master branch to see that the shop-staging branch will automatically be kept in sync.

Conclusion

We're quite happy with this approach. GitHub Actions deem to be very flexible. It'd have been even simpler if Netlify would support this use case out of the box, but since that's not the case syncing two branches isn't too bad either.

The approach described in this post can also be used when using split-testing which is built into Netlify and allows you to test two (or more) variants of a website. It's not something we're using ourselves but with split-testing come the same problems as described in the problem statement.

Finally, I have to note that we're currently only using one feature flag. This approach might not scale well if you want to use lots of feature flags because you might want to deploy separate staging sites for all combination of flags.

Happy roasting!