The open source firmware can be used as-is if you just want to access a device using the built-in terminal emulator or it can serve as a starting point for custom development. ConsoleCast can be seen as a normal development board for prototyping your own solutions but with the example firmware you already have a rich set of features and functionality. We encourage users to clone the project and enhance it with their own ideas. Maybe other users can benefit from your enhancements too.
The code is written using Espressif's ESP-IDF framework. You will need to install the ESP-IDF framework to work with the code. Set the target chip to ESP32S2 as ConsoleCast is using the S2 variant. The example code consists of back-end code, running on ConsoleCast and a front-end part, running inside the browser. ConsoleCast comes pre-installed with the latest version but you can re-flash it with your modified code using the USB-C connector or by using a UART to USB bridge attached (see about page).
You don't have to use the webpage that's flashed onto ConsoleCast, you can write your own HTML/JS as well. You don't need a webserver for this to work. Just create a local html file and open it using the local file prefix "file:///". In your JS code you create a Websocket to "wss://cc.local/ws".
The code has two main parts for the serial port and for the USB port. The code for using the serial port is fairly straight forward and uses the plain IDF functionality for serial communication. The USB host code currently is using the USB Host Library API which is in beta right now. We will try to keep the code up-to-date with later releases. Before using USB host functionality ConsoleCast has to be configured to reverse the VBUS power direction. That is, in host mode, ConsoleCast no longer draws power but should supply power to the USB bus. The reversal is done in code by setting VBUS_R high (see code).
Xterm JS is used for the terminal. All characters typed are sent to ConsoleCast (over WebSockets) and passed on to the currently active port. Characters received by ConsoleCast from the attached device are sent to the browser. Only the tokens are handled as stated above.
The certificate ConsoleCast is using, is embedded in the firmware during the build of the firmware. If you want to generate your own certificate it should be placed in a "cert" directory inside the "main" directory. This directory and certificate files are not published on Github for obvious reasons. The "component.mk" and "CMakeLists.txt" files inside the "main" directory reference the certificate files:
For generating your own certificate files you need to install OpenSSL. The way to do this, fully depends on your operating system. There are many instructions and tutorials available on the Internet. After installing you need a config file (see example below). Then you can generate your certificate files using "openssl" with this config file (see example below).
When you have your certificate files generated and put in the "main/cert" directory, you can build and flash the firmware using the normal IDF tools. You can either use the USB-C connector (DFU mode) or use an external USB to UART module (see about page).
The normal sequence would be "idf.py set-target esp32s2" to clean the build directory and setting the target (ESP32s2) and then using one of the methods below. Note that for DFU you will have to put ConsoleCast in flash mode by pressing reset (the EN switch) or from OFF to ON while holding down the BOOT switch.
In the IT systems arena you could think about automating certain provisioning tasks or update/upgrade tasks for network equipment. You could "play" scripts or record config data. You can choose to customise the firmware or to implement more functionality outside of ConsoleCast with scripts that communicate using WebSockets or some other mode of communication.
The easiest way to get going is to leave the firmware as is but create your own front-end code (webpage for example) that communicates using Websockets to the standard ConsoleCast firmware. As an example we published a simple SCPI front-end example for the Owon XDM2041 multimeter.
The JS code in this simple example scans every websocket message for tokens '§!' (link up) and '§®' (port connected). When the link to ConsoleCast is up, the code sends a string for the COM port settings: '§©9600,8,0,1,0,0'. The format used here is:When the '§®' (port connected) token is encountered, the SCPI command for requesting the current measurement is sent every second: 'MEAS1?\r'. You need to close each command with a return character '\r'. The Owon returns measurement readings in scientific format, so the readings are converted before display. You can find the programming manual for the complete command-set here.