The Ports-and-Adapters Architecture for Embedded HMIs

The ports-and-adapters architecture (a.k.a. hexagonal architecture) is based on the same idea as USB ports and adapters. USB adapters enable PCs to communicate with embedded devices over CAN, RS232, (W)LAN or BLE. The USB port hides from the PC which technology is used for the communication - as a good interface should do. Different companies can manufacture the adapters as long as they comply with the USB interface.

A typical machine HMI has a UI, machine, accounting and monitoring port. These ports are the interface between the application core implementing the business rules and the adapters connecting the HMI to the user, the cloud, databases and the rest of the machine. Ports lift the abstraction level from concrete technologies like SQL, J1939, Qt and MQTT to the business domain.

The machine port, for example, hides from the core whether the machine adapter uses the J1939 or OpenCAN protocol over CAN bus or Ethernet. If the manufacturer decides in 5 years to switch from CAN to Ethernet, it can do so without impacting the core and the other adapters. The architecture becomes loosely coupled, cohesive and easy to extend.

Each port has at least two adapters: one for production and one for testing. Test adapters are either test cases or mocks. As the core, they are technology agnostic and I/O-free. We can write I/O-free tests for the core. Such tests are ideally suited for TDD or BDD.

Conway’s law tells us that the software architecture mirrors the organisation structure. So, it is not surprising that the architecture more often than not resembles a big ball of mud. We can avoid this by inverting Conway’s law. We map the core and adapters to separate teams. The ports become the team APIs. Some teams can be merged - especially if too small. Other teams should not be merged.

The ports-and-adapters architecture has gained a lot of traction in enterprise software, but is little known in the embedded world. This is unfortunate, because it is an excellent architecture not only for embedded HMIs but also for firmware.