1. Purpose

The purpose of this document is to describe the F1093 firmware.

2. Development Information

2.1. Toolchain

The following tools and libraries are used to build this library:

Type Name Revision

IDE

Arduino IDE

2.3.2

Arduino Board

esp32 by Espressif

3.2.0

2.2. Target

This firmware is only designed to be ran on an ESP32 on an E1041 PCBA.

3. Functional Description

The F1093 firmware controls up 4x IV-8 Vacuum Fluorescent displays.

This firmware attempts to connect to a WIFI network on startup. The WIFI SSID and password are initially defined in a header file wifiDefault.h.

3.1. Display Modes

This firmware has the following run-time modes for the display:

  • "off": The displays are disabled, nothing is displayed

  • "numb": Shows a static number on the display. Useful for host updated numeric display

  • "time": Shows the current time based off the timezone set.

On startup the firmware defaults to "time"

3.2. Time Format

When displaying time, this firmware can present that in the following modes:

  • 24hr: Displays the time as HH:MM in 24-hour format

  • 12hr: Displays the time as HH:MM in 12-hour format. No AM/PM indicator can be shown in this mode

  • metric: Displays the time as HH:MM in metric format. See https://metric-time.com/ for more information on this format

3.3. NVM

Note
 This is not implemented yet

This firmware stores some parameters in non-volatile memory (nvm). The esp32-arduino’s EEPROM is used, handling data storage and integrity. The following table describes what is stored.

Offset Length Type Description

0

1

byte

NVM magic to see if something is written. Should be 0x5A

1

32

str

WIFI SSID to connect to

33

32

str

WIFI password to connect to

3.4. Communication

This firmware can be communicated with over the following interfaces:

  • Serial over USB, 115200 baud, 8N1

  • TCP over Wifi, port 23

This firmware can handle both connections simultaneously.

All command frames sent to/from the device are in ASCII text mode, with either carriage-return (\r) or line-feed (\n) ending per frame.

3.4.1. Wifi

This firmware handles being connected over Telnet directly, allowing to connect to this firmware over the built-in telnet commands to many UNIX systems.

The following telnet commands are handled, some of which are automatically sent when starting a telnet session:

  • DO

  • WILL

  • Interrupt Process, including waiting for timing-mark to responds with a new line and flush the internal receive buffer

This firmware also implements a "exit" command to close a Telnet connection.

This firmware set it’s hostname to esp32-f1093.

3.4.2. Debug UART

A seperate debug UART exists, only accessible on the board over the tag-connect header. This is used for this firmware and ESP32’s internal debugging.

If the C define DEBUG_ENABLED is set in common.h, all debug messages are passed through this interface.

4. Commands

The commands are mostly structured as verb-noun system; the verb dictates the action, and noun is what to apply the verb to. For example "get mode" requests to "get" the "mode". The verb and noun are space delimited. Any argument(s) to the command are also space delimited.

If a command doesn’t sent back a return value, If a return value is not specified for a command, an acknowledgment (ACK) is sent back as the string "ok". Any not-acknowledgments (NACK) are sent as "error: X", where X is a human description of the error. Any command can sent a NACK if the command failed to execute.

The following table list all commands supported.

Verb Noun Arguments Return Desc

ping

pong!

ping/pong. Useful for checking if the firmware is functional

set

mode

[str], mode, either:

  • 'off'

  • 'numb'

  • 'time'

Set the new display mode, which is the same string as described in Display Modes

n

[int], The number to display to in "numb" mode

ACK only if in "numb" mode

timeFormat

[str], The new time format, either:

  • '24hr'

  • '12hr'

  • 'metric'

Sets the displayed time format, which is the same string as described in Time Format

uartBaud

[int], The new baud rate

Switches the main UART baud rate

get

version

The firmware version

mode

The current mode

See Display Modes

n

The current displayed number

time

The current time, in the set timezone

timeFormat

The time format

See Time Format

ip

The current IP address, or "none" if not connected to WiFi

update

begin

The firmware size in bytes

Starts a firmware update

cont

The number of bytes to send, then the raw bytes after reception of the first ACK

ACK, followed by another ACK after raw bytes received

When this command is received with the number of bytes to send, an ACK is sent. The firmware then expects that many bytes (not ASCII) to be received, in which another ACK will be sent after all expected bytes are received

end

Finishes the firmware update process

cancel

Cancels any on-going firmware update process

exit

In Telnet mode, this command sends the required Telnet commands to disconnect.

reboot

Restarts the ESP32