Compilation

The recommended tool to compile and upload the AR488-ESP32 firmware is platformio either using the VSCode based IDE or using direcly the command line tools (solution used in this document).

Configuration

The entry point for choosing the target board to compile the formware for, as well as configuring the compile-time options is the platformio.ini file located at the root of the source code directory.

Besides the main [platformio] section, any [env:xxx] section defines a new target for with the firmware can be built.

The main configuration for a given target is achieved via a number of compiler variable given as build flags.

Possible variables are:

  • AR488_CUSTOM: if set, the pin mapping must be provided via a series of build flags.

  • AR488_WIFI_ENABLE: if set, enable the ESP32 wifi for wireless communication protocol.

  • AR488_BT_ENABLE: if set, enable the ESP32 Bluetooth for wireless communication protocol.

  • USE_MACROS: enable support for run-time configurable macros (see :ref:`macos`_)

  • HAS_HELP_COMMAND: enable support for the ++help command; on limited boards (like some AVR boards), this can consume too much storage memory and make the firmmware not fit in the flash storage. On ESP32 boards, there is no reason not to enable it.

  • BOARD_HAS_PSRAM: activate usage od PSRAM on ESP32 boards that have support for it; this is generally required if you have many features enabled (thus need mode RAM than the stock one, especially when using wifi etc.).

  • SN7516X: enable support for SN76160 and SN75161/2 transceivers between the ESP32 board and the GPIB bus. If set, you need to configure also the control pins of the transceivers (see below).

  • DIOX=nn: set the pin mapping for the GPIB data pin Dx (used if AR488_CUSTOM is set).

  • REN|IFC|NDAC|NRFD|DAV|EOI|ATN|SRQ=nn: set the pin mapping for GPIB control pins (idem).

  • SN7516X_TE|SN7516X_DC=nn: pin mapping for the SN7616x TE and DC pins

  • SN7516X_SC=nn: pin mapping for the SN76162 SC pin (only required if using the SN75162B transceiver).

TO enable one of the features listed above, just add the -D XXXFEATURE in the build_flags section of your build target.

The esp32dev example below is a configuration section for a ESP32-devkitc based board with SN75160/2 transceiver and all options enabled:

[env:esp32dev]
platform = espressif32
framework = arduino
board = esp32dev
board_build.partitions = ttgo.csv
build_flags =
     -D AR488_CUSTOM
     -D USE_MACROS
     -D HAS_HELP_COMMAND
     -D AR488_WIFI_ENABLE
     -D BOARD_HAS_PSRAM
     -D AR488_BT_ENABLE
     -D SN7516X -D SN7516X_TE=15 -D SN7516X_DC=2
     -D SN7516X_SC=0  # for 75162
     -D DIO1=33 -D DIO2=32 -D DIO3=26  -D DIO4=25
     -D DIO5=14 -D DIO6=27 -D DIO7=13  -D DIO8=12
     -D REN=23  -D IFC=22  -D NDAC=21  -D NRFD=19
     -D DAV=18  -D EOI=17  -D ATN=4    -D SRQ=16

Note: this example uses a custom partition scheme for the flash memory (otherwise the full-featured firmware does not fit in a sigle A/B partition).

Building

Once the target is properly configured in the platformio.ini file, you can build it using the standard platformio environment. Using the cli tools, building the esp32dev target would be:

AR488-ESP32$ pio run -e esp32dev
Processing esp32dev (board: esp32dev; platform: espressif32; framework: arduino)
----------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
CONFIGURATION: https://docs.platformio.org/page/boards/espressif32/esp32dev.html
PLATFORM: Espressif 32 (6.0.0) > Espressif ESP32 Dev Module
HARDWARE: ESP32 240MHz, 320KB RAM, 4MB Flash
DEBUG: Current (cmsis-dap) External (cmsis-dap, esp-bridge, esp-prog, iot-bus-jtag, jlink, minimodule, olimex-arm-usb-ocd, olimex-arm-usb-ocd-h, olimex-arm-usb-tiny-h, olimex-jtag-tiny, tumpa)
PACKAGES:
 - framework-arduinoespressif32 @ 3.20006.221224 (2.0.6)
 - tool-esptoolpy @ 1.40400.0 (4.4.0)
 - toolchain-xtensa-esp32 @ 8.4.0+2021r2-patch5
Converting AR488.ino
LDF: Library Dependency Finder -> https://bit.ly/configure-pio-ldf
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 33 compatible libraries
Scanning dependencies...
Dependency Graph
|-- EEPROM @ 2.0.0
|-- Preferences @ 2.0.0
|-- WiFi @ 2.0.0
|-- BluetoothSerial @ 2.0.0
Building in release mode
Compiling .pio/build/esp32dev/src/AR488.ino.cpp.o
Retrieving maximum program size .pio/build/esp32dev/firmware.elf
Checking size .pio/build/esp32dev/firmware.elf
Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
RAM:   [==        ]  17.2% (used 56464 bytes from 327680 bytes)
Flash: [=======   ]  74.0% (used 1503421 bytes from 2031616 bytes)
================================ [SUCCESS] Took 3.67 seconds ================================

Environment    Status    Duration
-------------  --------  ------------
esp32dev       SUCCESS   00:00:03.671
================================ 1 succeeded in 00:00:03.671 ================================

The generated firmware file is located in .pio/build/esp32dev/firmware.bin.

Note: if you do not specify a target (-e xxx) then all the targets defined in the platformio.ini file will be built, which can take quite a while.

Uploading this to the board is then a simple matter of using the command:

AR488-ESP32$ pio run -e esp32dev -t upload
[...]