Skip to main content

Setting Up Your Site

Defining messages as Protocol Buffers will start to pay off. With the generated code in place and the firmware compiled and placed in a known location in our project structure, our project website becomes our user interface to our board and its firmware!

Note: Interacting with your board via serial port requires using a Google Chrome or Microsoft Edge web browser.

Running your site locally​

Qroma projects ship with Docusaurus integration by default. This means they support Markdown and React components out of the box so that documentation and adding user interface elements is as simple as we could make it. Additionally, Docusaurus itself has good documentation and support.

Qroma can help you quickly look at your website files with the site edit command. The full command below opens your configured editor to access your board's website project in edit mode.

qroma site edit :my-qroma-project

You can run the site in local development mode with the site run command.

qroma site run :my-qroma-project

Once it's running in dev mode, updates you make in the site directory will be reflected in your pages as you make them.

Loading firmware from your site​

Your project site is set up to make it simple for users to install the firmware built for their boards. Follow the Install Firmware link in the nav bar and click the install button for the board you are using. Follow the instructions in the dialog and the firmware will start installing.

Publishing a new firmware version is now a simple matter of making changes, building the firmware, and running qroma site bundle again.

Qroma uses ESP Web Tools to get firmware from the webserver onto your ESP32.

Interacting with your device​

Your project site is set up to use your project's command message and interpret responses from your device. Follow the Command Device link in the nav bar. You will see fields that map to the message types you have defined with protocol buffers. Click the Start Connection button to start the web serial connection with the device and interact with the board.

Deploying your project site on github​

At this point, our project is aware of commands and our firmware can process it. Now, how can a user who isn't you interact with it? This is where embedded devices can really start to get complicated. First, how do we get our firmware onto our device board? No, scratch that... how could someone that ISN'T us get the firmware on THEIR device board?

To summarize, your project doesn't do much good to show off your work or help other people use your project. To do that, Qroma projects are set up to be able to deploy to Github Pages quickly and easily so you can share your project links as you see fit.

With a little bit of configuration, we can configure our project so that it can be published as a static site which hosts the firmware so that anyone can install and then interact with our embedded device project!

Update docusaurus.config.js file at root of site directory.

  • set organizationName (usually your GitHub org/user name)
  • set projectName (usually your repo name)

Iterate​

The steps above focus on giving you, the developer, a set of tools so you can rapidly iterate on, document, and share changes as you discover the potential of your project.