Posted by Aaron Elijah on 4th Jul 2021

BotBlox Management Software Release

Quick Links

  1. Firmware on GitHub
    Visit GitHub for Firmware implementation
  2. Software on GitHub
    Visit GitHub for Software implementation
  3. CLI Documentation
    Visit Notion for Documentation
  4. Video Demonstration
    Visit YouTube for Video Demo

We have been asked questions from customers ever since Botblox launched its first product (the SwitchBlox in 2017) wondering our products fit their use case. A regular theme among these questions was if BotBlox offered managed switch capability. Instead of having the default unmanaged state of all ports being part of the same network, many customers were curious to know if they could separate the ports into separate VLANs, for example. What about configuring port mirroring so that traffic from multiple ports is forwarded to a mirror port – an essential network analyst tool.

We haven’t been idle to these questions and are very excited to announce that BotBlox is releasing an alpha version of software and firmware that will allow customers to configure managed settings on the SwitchBlox.

Release Overview

Our new solution for configuring managed settings is split into two parts: (1) software and (2) firmware. The firmware is programmed and saved into the application memory on the microcontroller that lives on the SwitchBlox. It runs every time the SwitchBlox is power cycled. The software is a software package, written in Python 3.8, behaves as a CLI application. The software sends commands to the firmware via a generic USB-to-UART converter. The firmware parses that data to the Ethernet chip on the Switchblox, which changes it’s operations accordingly. More than that, the commands you specified are saved to internal EEPROM in the microcontroller so that every time the SwitchBlox is power cycled, the saved commands are resent to the Ethernet chip. We have so far released configuration options for port-based VLANs and port mirroring, with plans to release new features over the coming months.

See the diagram below for a 3-step outline that shows the simplicity of the configuration. First, upload and run the firmware using STM32CubeIDE toolchain with a J-Link Probe. Second, use the software and a USB to UART converter to write commands to the SwitchBlox. Third, once you’ve programmed the SwitchBlox once, you can use it for VLAN configuration or port mirroring, with more options being added in the future!

How does the firmware work?

Custom MDIO bit-banger library

From a high level, our firmware is very simple. All it does is listen to commands received from the software running on a computer and parses that data to the Ethernet chip. The code to convert a user’s input to commands which configure the Ethernet chip is abstracted away from the firmware and instead lives in the software (a much more developer-friendly environment!). This simplifies the architecture of the firmware considerable, making it simpler for developers to understand.

However, there are many aspects of the firmware worth mentioning. We made a custom library to implement a bit-banger, which we use to talk to the Ethernet chip. The Ethernet chip has a series of Media-Independent Interface (MII) registers that dictate the operation of each PHY. However, the serial bus defined for MII (called MDIO, SMI or MIIM) is not part of the STM32CubeIDE Hardware Abstraction Library: STM32CubeIDE is part of the toolchain we use to write application code for the microcontroller; an STM32L0-series controller.

We had to develop our library to write to the MII registers using only the datasheet of the Ethernet chip as a reference. Through much trial and error, we succeeded to make a proof of concept. From there, we knew the project was feasible, without changing the design of the SwitchBlox.


The other design choice of interest is the use of Direct Memory Access hardware (DMA). A DMA controller comes inbuilt on the STM32 microcontroller, running as a second master device on the system bus (along with the Core). To understand the reason for this, we need to know how the Core is transferring data it receives from UART in the ordinary case.

UART is a peripheral of the processor and UART data registers store incoming UART RX data. Depending on whether the Core configures the UART to be blocking or non-blocking, either a timer or condition of the data register being full will trigger an interrupt to the Core. The Core then begins a transaction transferring bytes from the UART data register to SRAM (volatile memory used to store variable values). During this time, the Core is blocking, so it can’t do much else during this transfer. Correspondingly, there is a performance cost associated with this. However, we mitigate this cost with the use of a DMA.

As before, bytes are stored in the UART peripheral data registers. However, instead of triggering an interrupt to the Core, the interrupt is triggered to the DMA. The DMA initiates a transaction to transfer bytes from the peripheral data registers to SRAM (volatile memory for variables used in the application code) – the same function as the Core. Therefore, the Core has less to do; freeing it up to perform other functions.

Whilst the firmware code is delightfully simple in its application, implementing best practices to optimise the hardware will save developer time in future versions of the firmware. This attitude hopefully lays the groundwork for future firmware capability.

Firmware-Software integration

As stated previously, a new software CLI application called botblox, written in Python, is the other half of this release. The software’s role is to convert user input data typed into the command line into bytes that write the MII registers on the Ethernet chip. Those bytes are then sent to the microcontroller running our firmware, which parses and writes them to the Ethernet chip using the method described above. Instead of the firmware containing the code logic that converts human-readable commands (such as vlan --group 1 2, which sets up a VLAN group with member ports 1 and 2), the logic is in software, which can be more easily accessed by the user or developer. We encourage readers to look at the documentation for the full list of current configurations options on the CLI. We have purposefully implemented VLAN and Port mirroring capability first: we have found these are the most frequently requested. However, we won’t stop there and will continue expanding the configurations in the coming months.

Software distribution

On distribution, botblox is downloadable in a single command: pip install botblox. So long as you have a suitable Python version installed on your system {link to suitable Python language version}, you should have no problems running this application regardless of OS.

In summary, we have created a full toolchain for customers to use to configure the SwitchBlox. So far we support configuring VLAN groups and port mirroring. We have engineered many interesting optimisations within our code that will help futureproof the architecture against further innovation.

The future

There is so much promise in the firmware/software. We will continue to add features and support our clients using our software post-release. We will continually critique our code for best practice and ensure that the code remains reusable and readable to developers. Furthermore, we want to expand the functionality of the CLI to make it even more interactive. Eventually turn the Python package into a useable dependency that is used in application code, as we believe that will further extend the usability for our customers.

Open source

Many observers may be curious to see why we have decided to release the alpha version, instead of a beta or stable version. Firstly, we want to be customer-driven: giving customer’s a good look now gives confidence in the design going forward. Secondly, we intend the software and firmware to transition to a community project, with developers from our clients or hobbyists getting involved. Having a community of developers on board enables us to be closer to our customer’s hardware and software development teams. Ultimately, this makes us much more responsive to any new features they need. We don’t want this software to exist in a vacuum, we want it to be very close to our customers.