Documentation

• 1: Tanmatsu
• 2: NE-HCS12SS59T-R1 I2C VFD
• 3: OpenBMC
• 3.1: ASRock Rack
• 3.1.1: ASRock Rack X570D4U
• 3.1.1.1: ASRock Rack X570D4U mainboard: pinout
• 3.1.1.2: ASRock Rack X570D4U mainboard: I2C busses
• 3.1.1.3: ASRock Rack X570D4U mainboard: GPIO
• 3.1.1.4: Programming SPI flash with an FT2232 breakout board
• 3.1.1.5: ASRock Rack X570D4U mainboard: temperature sensors
• 3.1.1.6: ASRock Rack X570D4U mainboard: fans
• 3.1.2: ASRock Rack PAUL
• 3.1.2.1: ASRock Rack PAUL: GPIO

1 - Tanmatsu

Tanmastu is the dream terminal device for hackers, makers, and tech enthousiasts. Based around the powerful ESP32-P4 microcontroller, this device provides an accessible way to make, hack, and tinker on the go.

Tanmatsu lets you program on the go and communicate over long distances using LoRa whilst also providing advanced connectivity and extendability options for hardware hacking and development.

Features

Tanmatsu is based around the upcoming ESP32-P4 SoC by Espressif: their most powerful RISC-V microcontroller yet. With its 400MHz dual-core processor and 32MB of built-in PSRAM it makes the ideal platform for powerful processing on the go whilst still maintaining the ease of use one expects form a microcontroller platform.

In addition to the powerhouse ESP32-P4 application processor we have included an ESP32-C6 WiFi, Bluetooth Low Energy, and IEEE802.15.4 wireless radio module. This module enables wireless internet access, as well as access to local mesh networking like Thread and ZigBee in a very hacker friendly way.

A LoRa radio module provides access to LoRa networks such as long distance mesh network services and (G)FSK modulated classic 433 or 868MHz communication, depending on the LoRa module installed.

The device has 16MB of built-in flash storage for firmware and applications, expandable using a micro SD card. The micro SD card socket supports SD cards at 3.3v and 1.8v voltage levels (SDIO 3).

A big MIPI DSI display and the QWERTY keyboard make for great ease of use both in the workshop and on the go.

In addition to all the built-in functionality the device allows for expansion modules using its two expansion ports. The back facing expansion port allows for expanding functionality using what we call “personality modules”. While the side facing expansion port allows for easily connecting a wide variety of PMOD and SAO accessories.

A QWIIC style expansion connector allows connecting the device to a wide range of sensors available from manufacturers such as Sparkfun and Adafruit, it supports both the I2C and the new I3C communication bus standards.

Included with the community version of the Tanmatu is a case. This sturdy case will allow the device to be used everywhere whilst keeping the electronics safe and protected.

Software

The firmware provides basic tools for creating applications directly on the Tanmatsu itself. In addition it provides access to a marketplace for applications where developers can publish their creations. Apps can be downloaded and installed directly on the device and launched from the launcher menu.

Hardware features - summary

• ESP32-P4 dual-core 400MHz RISC-V microcontroller with 32MB of built-in PSRAM
• ESP32-C6 radio module for WiFi, BLE and IEEE 802.15.4 mesh networking connectivity
• Ai-Thinker Ra-01S or Ra-01SH module for long range communication using LoRa modulation and generic (G)FSK modulation for short range classic wireless radio applications at 433MHz or 868MHz respectively
• 16MB of built-in flash storage for firmware and applications
• Fast and big 800x480 MIPI DSI display
• QWERTY keyboard
• Lithium polymer battery
• Audio output via headphone jack and speaker
• I2C and I3C connectivity via Qwiic compatible JST SH style connector
• SD card socket supporting SD cards at 3.3v and 1.8v voltage levels (SDIO 3)
• Side facing expansion port with both SAO and PMOD capabilities
• Back facing expansion port for expanding functionality using personality modules

Software features - summary

• Launcher menu for easy access to multiple applications and firmwares
• Access to user generated content and applications repository via the store app
• Built-in text editor for writing notes and code on the go
• Python interpreter application
• Javascript interpreter application
• C compiler application
• Meshtastic compatible LoRa messenger application

Open source

The hardware design is fully open source and available under a permissive license (CERN-OHL-P). The design was made in the open source PCB CAD application KiCAD, allowing everyone to edit the design without any roadblocks. We’ve also included manufacturing files so people could order the design themselves if they wish to experiment.

The board support package and launcher firmware will also be made fully open source under a permissive license (MIT), enabling modifications and improvements by the community and granting users and developers complete freedom and control.

Personality modules

Whilst the base Tanmatsu device already provides lots of functionality we plan on creating and making available multiple personality modules for extending the functioality in ways useful to you.

More information about the planned personality modules will be made available soon.

2 - NE-HCS12SS59T-R1 I2C VFD

Now on Tindie: I2C VFD display

What is it?

A Samsung HCS-12SS59T 12 character vacuum fluorescent display connected to a custom driver board which takes away all the difficulties of using such a display. The driver board does everything for you, from step-up voltage generation to having a microcontroller that translates between the display and an easy to use I2C interface.

Why did you make it?

I like weird and wonderful displays and this display deserves a spot in cool DIY projects. Unfortunately it is not exactly plug-and-play for use in Arduino, MicroPython or Raspberry pi projects.

What makes it special?

Everything is handled on-board, from generating the required voltages to handling the display control signals. All you have to do is hook up this module via I2C using the QWIIC / Stemma QT connectors on this board. There is two of them allowing for easy daisy chaining with more displays or other QWIIC/Stemma QT boards.

Sources

The hardware design files can be found in the hardware repository and the firmware can be found in the firmware repository.

How to use the device

The device can be connected to a microcontroller via the standardized QWIIC interface.

The device is compatible with a supply voltage of 3.3 volt. The I2C interface requires a working voltage of 3.3 volt as well.

I2C interface

The default I2C address is 0x10. The address can be changed by bridging the address jumpers on the board. This allows for modifying the I2C address in the range 0x10 up to 0x2F. Jumper 0 increases the address by 1, jumper 1 increases the address by 2, jumper 3 increases the address by 4 and jumper 4 increases the address by 8.

Register map

Scrolling modes

0 = Scrolling disable
1 = Scroll left (increment display offset)
2 = Scroll right (decrement display offset)

Usage

Basic usage

At power on the display is automatically enabled. Writing ASCII text to registers 10 through 255 will make the text appear on the display.

To move the position in the buffer which is shown on the display you can write an offset to register 1 (display offset).

System control

To turn off the display write 0 to bit 0 of register 0, to turn on the display write a 1 to bit 0 of register 0. The LED can be controlled using bit 2 of register 0.

Scrolling

The automatic scrolling feature automatically updates the value of register 2 (display offset) to make the text shown on the display scroll without interaction by the bus master.

To enable automatic scrolling first write the maximum value the offset register should reach by setting the value of register 2 (scroll length). To stop scrolling once the last character of a string of text is shown on the rightmost position of the display set the value of this register to the length of the string minus 12 (the amount of characters the VFD can display).

Then write the speed at which you wish the characters to scroll into registers 4 and 5. This value is a 16-bit number representing the amount of milliseconds to wait before moving to the next character.

If scrolling was used before then resetting the current display offset to 0 makes sure the display starts scrolling from the beginning of the text.

To start scrolling write 1 to register 3. This will cause the text to scroll to the left automatically. Scrolling will stop once the scroll length value is reached. To automatically reset to the start of the string the loop function can be enabled by writing 17 (16, loop enable + 1, scroll left) to register 3.

For better readability adding 12 spaces to the front of the string to be scrolled is adviced, this makes the scrolling text start by scrolling in from the right into a blank screen.

Example Arduino sketch

The following Arduino sketch shows basic usage and how to use the built-in automatic scrolling features of the product.

// This example sketch may be freely used and considered in the public domain
// in countries where releasing code into the public domain is not possible
// this code may be used under the terms specified in the CC0 license
// https://creativecommons.org/public-domain/cc0/

#include <Wire.h>

#define VFD_REG_CTRL         0
#define VFD_REG_OFFSET       1
#define VFD_REG_SCROLL_LEN   2
#define VFD_REG_SCROLL_MODE  3
#define VFD_REG_SCROLL_SPEED 4
#define VFD_REG_DATA         10

#define VFD_SCROLL_DISABLE   0
#define VFD_SCROLL_LEFT      1
#define VFD_SCROLL_RIGHT     2

const int16_t I2C_ADDR = 0x10;

// Functions for reading and writing

void vfd_read_regs(uint8_t reg, uint8_t* val, uint8_t len) {
  Wire.beginTransmission(I2C_ADDR);
  Wire.write(reg);
  Wire.endTransmission(false);
  Wire.requestFrom((uint8_t) I2C_ADDR, (uint8_t) len);
  for (uint8_t index = 0; index < len; index++) {
    val[index] = Wire.read();
  }
  Wire.endTransmission();
}

void vfd_read_reg(uint8_t reg, uint8_t* val) {
  vfd_read_regs(reg, val, 1);
}

void vfd_write_regs(uint8_t reg, uint8_t* val, uint8_t len) {
  Serial.print("I2C write to register " + String(reg) + ": ");
  Wire.beginTransmission(I2C_ADDR);
  Wire.write(reg);
  for (uint8_t index = 0; index < len; index++) {
    Serial.print(String(val[index], HEX) + ", ");
    Wire.write(val[index]);
  }
  Serial.println();
  Wire.endTransmission();
}

void vfd_write_reg(uint8_t reg, uint8_t val) {
  vfd_write_regs(reg, &val, 1);
}

// Functions for using the control register

void vfd_control_led(bool state) {
  uint8_t val = 0;
  vfd_read_reg(VFD_REG_CTRL, &val);
  Serial.println("LED, READ  " + String(val, HEX));
  val &= ~(1 << 2); // Turn off the LED
  if (state) {
    val |= (1 << 2); // Turn on the LED
  }
  Serial.println("LED, WRITE " + String(val, HEX));
  vfd_write_reg(VFD_REG_CTRL, val);
}

void vfd_control_test(bool state) {
  uint8_t val = 0;
  vfd_read_reg(VFD_REG_CTRL, &val);
  val &= ~(1 << 1); // Turn off the test mode
  if (state) {
    val |= (1 << 1); // Turn on the test mode
  }
  vfd_write_reg(VFD_REG_CTRL, val);
}

void vfd_control_enable(bool state) {
  uint8_t val = 0;
  vfd_read_reg(VFD_REG_CTRL, &val);
  val &= ~(1 << 0); // Turn off the VFD
  if (state) {
    val |= (1 << 0); // Turn on the VFD
  }
  vfd_write_reg(VFD_REG_CTRL, val);
}

void vfd_control(bool enable, bool test, bool led) {
  uint8_t val = 0;
  if (enable) {
    val |= (1 << 0);
  }
  if (test) {
    val |= (1 << 1);
  }
  if (led) {
    val |= (1 << 2);
  }
  vfd_write_reg(VFD_REG_CTRL, val);
}

// Functions for using the scroll features

void vfd_set_offset(uint8_t offset) {
  vfd_write_reg(VFD_REG_OFFSET, offset);
}

void vfd_set_scroll_length(uint8_t len) {
  vfd_write_reg(VFD_REG_SCROLL_LEN, len);
}

void vfd_set_scroll_mode(uint8_t scroll_mode, bool scroll_loop) {
  uint8_t val = scroll_mode & 0x0F;
  if (scroll_loop) {
    val |= (1 << 4);
  }
  vfd_write_reg(VFD_REG_SCROLL_MODE, val);
}

void vfd_set_scroll_speed(uint16_t scroll_speed) {
  uint8_t values[2];
  values[0] = (scroll_speed) & 0xFF;
  values[1] = (scroll_speed >> 8) & 0xFF;
  vfd_write_regs(VFD_REG_SCROLL_SPEED, values, sizeof(uint16_t));
}

// Functions for using the text buffer

void vfd_write_text(String text) {
  // This function writes an ASCII string into
  // register 10 to 255

  const size_t max_len = 245; // can store text in registers 10 to 255
  size_t len = text.length();

  if (len > max_len) {
    // Silently limit the length of the string
    len = max_len;
  }

  Wire.beginTransmission(I2C_ADDR);
  Wire.write(VFD_REG_DATA);
  for (size_t index = 0; index < len; index++) {
    Wire.write(text[index]);
  }
  Wire.endTransmission();
}

// Functions for Arduino program

void setup() {
  Serial.begin(115200);

  Serial.println("Initialize I2C bus");
  Wire.begin(); // Initialize the I2C bus

  // Configure the display and show a message
  Serial.println("Configure the display and show a message");
  vfd_set_scroll_mode(VFD_SCROLL_DISABLE, false); // Disable scrolling
  vfd_set_offset(0); // Move to beginning of text buffer
  vfd_write_text("Hello world ");
  vfd_control(true, false, true); // Turn on VFD and LED
  delay(1000); // Wait a bit

  Serial.println("Demonstrate scrolling");
  String text = "            The quick brown fox jumps over the lazy dog 0123456789 !@$%^&*()-_=+";
  vfd_write_text(text);
  vfd_set_scroll_length(text.length() - 12); // Scroll until the last character of the string is on the most right character of the display
  vfd_set_scroll_speed(100); // Scroll one character every 100ms
  vfd_set_scroll_mode(VFD_SCROLL_LEFT, false); // Scroll left then stop
  vfd_control_led(false);
  delay(10000);

  vfd_set_scroll_mode(VFD_SCROLL_RIGHT, false); // Scroll right then stop
  vfd_control_led(true); // Turn on LED
  delay(10000);

  vfd_set_scroll_mode(VFD_SCROLL_LEFT, true); // Scroll left then loop
  vfd_control_led(false); // Turn off LED
  delay(20000);

  vfd_set_scroll_mode(VFD_SCROLL_DISABLE, false); // Disable scrolling
  vfd_write_text("            "); // Clear screen
  vfd_set_offset(0); // Move to beginning of text buffer
  vfd_control_led(true); // Turn on LED

  Serial.println("Starting counter loop");
}

uint32_t counter = 0;
void loop() {
  // Count as fast as we can
  vfd_write_text(String(counter));
  counter++;
}

What does it look like?

3 - OpenBMC

OpenBMC is an open source Linux distribution for Baseboard Management Controllers. Nicolai Electronics works on enabling more boards to run this open source firmware instead of manufacturer provided proprietary solutions. More information can be found on the board specific pages.

3.1 - ASRock Rack

ASRock Rack is a hardware manufacturer which has produced multiple mainboards and devices which should be capable of running OpenBMC. More information on the boards Nicolai Electronics is working can be found on the board specific pages.

3.1.1 - ASRock Rack X570D4U

Project status: in progress

The ASRock Rack X570D4U series of mainboards consists of three mainboards with an AMD X570 chipset and AM4 socket. ASRock Rack sells the board in three versions: a cost reduced version without a 10Gbit NIC (X570D4U), a version with an Intel 10Gbit NIC (X570D4U-2L2T) and a version with a Broadcom 10Gbit NIC (X570D4U-2L2T/BCM). These boards contain an Aspeed AST2500 BMC chip. A Baseboard Management Controller (BMC) is a small computer built into the motherboard that allows for out-of-band management. It allows for remote power control, KVM (remote keyboard, video and mouse) control, virtual media insertion and much more.

These parts make for quite a powerful system, unfortunately the operating system shipped by ASRock Rack is proprietary and dos not allow for easy modification. To allow for a more secure, transparent and customizable experience we are working on adding support for this mainboard to the mainline Linux kernel and the OpenBMC Linux distribution for BMCs.

Official documentation is provided in ASRock Racks manual for these mainboards. Not a all headers and connectors are described in this manual. The pinout of the undocumented connectors and headers can be found on the pinout page.
The BMC has a programming header, a debug serial port, I2C busses and GPIOs.

Project status

Enabling the use of the mainline Linux kernel and OpenBMC on this hardware is an ongoing effort. An initial port of OpenBMC missing most board specific features can be found here.

3.1.1.1 - ASRock Rack X570D4U mainboard: pinout

This page describes the undocumented headers and connectors on the ASRock X570D4U mainboard. The official manual for this mainboard describes most other connectors and headers.

BMC debug header

This header labeled BMC_DEBUG1 provides access to the debug serial port of the AST2500 SoC (UART 5). The UART works with 3.3v level signals and provides a 3.3v output and can be found on the bottom left of the mainboard.

Using this port you can access the U-Boot command prompt, the Linux bootlog and a shell.

BMC programming header

This header labeled BMC_PH1 provides access to the MX25L51245G 64MB flash chip containing the BMC firmware. Using an exernal SPI flash programmer this port allows for unbricking and easy reflashing of the BMC firmware during development.

This interface uses 3.3v level signals. Connecting the BMC RESET# pin to GND disables the AST2500, allowing an exernal programmer to reprogram the flash chip without interference from the SoC.

Manufacturing mode header

This header labeled MFG1 is connected to GPIO H4 of the AST2500 SoC. With the official firmware installed shorting this jumper makes the BMC boot into a special debug mode, dropping to a root shell on the BMC_DEBUG1 port. When running OpenBMC this GPIO is available for custom applications.

Chassis identification

These three headers labeled CHASSIS_ID1, CHASSIS_ID2 and CHASSIS_ID3 are connected to GPIO G1, G2 and G3 of the AST2500 SoC for ID1, ID2 and ID3 respectively. On production boards these headers appear to not have been installed, but they are functional. When running OpenBMC these GPIOs are available for custom applications.

3.1.1.2 - ASRock Rack X570D4U mainboard: I2C busses

This page describes the I2C busses and connected on-board devices on the ASRock X570D4U mainboard.

I2C bus 0

This bus is connected to the AUX_PANEL1 connector. SMBus alert for this bus is connected to GPIO 52 (G4) named input-aux-smb-alert-n.

I2C bus 1

This bus is used for controlling on-board devices that are used when the host is on.

PCA9557 IO expander

Nuvoton NCT6796D-R SuperIO

This chip can read the CPU and chipset temperatures. It should be possible to use the newly added nct6775-i2c driver to use this device.

Using the NCT6775-I2C driver

The OpenBMC port for the X570D4U already includes the nct6775-i2c driver in it’s kernel, but as the SuperIO device only appears on the bus when the host system is powered on the driver needs to be loaded in and unloaded based on power state changes. This has not been implemented yet.

The driver can be manually loaded in using the following command:

echo "nct6775 0x2d" > /sys/bus/i2c/devices/i2c-1/new_device

If the driver was loaded correctly then you should now be able to find a folder called hwmon in the device folder /sys/bus/i2c/devices/i2c-1/1-002d. This folder will contain a symlink to the hwmon interface for the SuperIO chip. If the folder is missing then your kernel does not include the nct6775-i2c driver.

Directly accessing and reading the temperature registers

Alternatively the temperatures can be read using this shell script, for which no kernel driver is required:

#!/bin/bash
i2cset -y 1 0x2d 0x4e 0x04
while :
do
    TSI0INT=$((16#$(i2cget -y 1 0x2d 0x09 | cut -f2 -dx)))
    TSI0FRC=$(($((16#$(i2cget -y 1 0x2d 0x0a | cut -f2 -dx)))>>5))
    TSI1INT=$((16#$(i2cget -y 1 0x2d 0x0b | cut -f2 -dx)))
    TSI1FRC=$(($((16#$(i2cget -y 1 0x2d 0x0c | cut -f2 -dx)))>>5))
    echo "TSI0_TEMP: $TSI0INT.$TSI0FRC °C / TSI1_TEMP: $TSI1INT.$TSI1FRC °C"
    sleep 0.5
done

Nuvoton W83773G

This device is available on the versions of the X570D4U which include a 10Gbit network adapter. It monitors the temperature of the 10Gbit NIC.

cat /sys/class/hwmon/hwmon0/temp2_input

I2C bus 2

This bus is used for connecting to exernal power supplies with SMBus monitoring support using the PSU_SMB1 connector. SMBus alert for this bus is connected to GPIO 54 (G6) named input-psu-smb-alert-n.

I2C bus 3

This bus has an unknown purpose.

I2C bus 4

This bus is used to connect to expansion cards inserted into the PCI-Express slots of the mainboard.

NXP PCA9545A I2C bus switch

I2C bus 5

This bus is connected to the BMC_SMB_1 connector. The BMC_PRESENT_1_N signal on the BMC_SMB_1 connector is connected to GPIO 132 (Q4) named input-bmc-smb-present-n.

I2C bus 7

This bus is used for connecting to the FRU EEPROM and the RAM DIMMs.

I2C bus 8

This bus is connected to the IPMB_1 connector.

3.1.1.3 - ASRock Rack X570D4U mainboard: GPIO

This page describes the GPIOs of the ASPEED AST2500 BMC on the ASRock X570D4U mainboard.

3.1.1.4 - Programming SPI flash with an FT2232 breakout board

Connection diagram

3.1.1.5 - ASRock Rack X570D4U mainboard: temperature sensors

This page describes the temperature sensors on the X570D4U.

Nuvoton NCT6796D-R SuperIO

This device can be accessed via I2C bus 1 at address 0x2D.

Nuvoton W83773G

This device can be accessed via I2C bus 1 at address 0x4C.

3.1.1.6 - ASRock Rack X570D4U mainboard: fans

This page describes the fan connectors on the X570D4U.

Fan connectors

Fan 1-3 connector pinout

Fan 4-6 connector pinout

3.1.2 - ASRock Rack PAUL

Project status: in progress

The ASRock Rack PAUL is a PCI-express add-in card for servers and workstations containing an Aspeed AST2500 BMC chip. A Baseboard Management Controller (BMC) is a small computer that allows for out-of-band management. It allows for remote power control, KVM (remote keyboard, video and mouse) control, virtual media insertion and much more.

These parts make for quite a powerful system, unfortunately the operating system shipped by ASRock Rack is proprietary and dos not allow for easy modification. To allow for a more secure, transparent and customizable experience we are working on adding support for this mainboard to the mainline Linux kernel and the OpenBMC Linux distribution for BMCs.

Official documentation is provided in ASRock Racks manual.

3.1.2.1 - ASRock Rack PAUL: GPIO

This page describes the GPIOs of the ASPEED AST2500 BMC on the ASRock Rack Paul card.