gex-docs/INI_FILES.md

# GEX's config files

GEX's configuration is stored in the internal flash memory in a packed binary form.
To make its editing easier for the user, the configuration is accessible as INI files
annotated by numerous comments explaining the individual config options.

## Filesystem access

There are two config files: `UNITS.INI` and `SYSTEM.INI`.

To access those files, the user presses the LOCK button (or removes the LOCK jumper),
which enables an emulated FAT16 storage that will appear on the host computer as a USB disk.
Some hardware platforms require that the jumper be removed before plugging in the USB cable,
as it can't trigger re-enumeration without external circuitry, which is missing on those
evaluation boards.

It's recommended to copy the INI files to a real disk before editing, as some editors create
temporary back-up files that can confuse the filesystem emulator. However, in-place editing
is also possible with some editors.

*This method is the only way of accessing the `SYSTEM.INI` file, which can reconfigure
the main communication port.*

After writing the changed files back to the virtual disk, it will briefly disappear
and an updated version of the files will become available for review.
This is when you can check for error messages.

To confirm the config modifications (they take effect imemdiately, but are not written to flash yet),
push the LOCK button again (or replace the LOCK jumper).

## API access

The `UNITS.INI` file may be accessed through the communication port.

The file is read using Bulk Read (see [FRAME_FORMAT.md](FRAME_FORMAT.md)) after sending a `INI_READ` request.

The modified file is written back using Bulk Write after sending a `INI_WRITE` request.

After writing the changed configuration, it may be persisted to flash using a `PERSIST_CFG` command.
This is not required if the new configuration will be used only temporarily; the original settings
will be restored after a restart.

## UNITS.INI file structure

The `UNITS.INI` file is interactive. The general layout is as follows:

```ini
## UNITS.INI
## GEX v0.0.1 on STM32F072-HUB
## built Mar 17 2018 at 17:53:15

# Overwrite this file to change settings.
# Press the LOCK button to save them to Flash.

[UNITS]
# Create units by adding their names next to a type (e.g. DO=A,B),
# remove the same way. Reload to update the unit sections below.

# Digital output
DO=
# Digital input with triggers
DI=btn,btn2
# (... more unit types here)

[DO:btn@1]
# Port name
port=B
# Pins (comma separated, supports ranges)
pins=2
# Initially high pins
initial=2
# Open-drain pins
open-drain=
```

- The keys in the `[UNITS]` section are lists of instances for each unit type.
  After adding a name to the list and saving the file, a new unit section will appear below, offering to configure
  the new unit as needed.
- Each unit section starts with `[type:name@callsign]`.The name must match the name used in the unit lists above.
  The callsign can be freely changed, as long as there is no conflict. Callsign 0 is forbidden and will be changed
  to a new unique callsign on save.
- If an error occurs during unit initialization, an error message will appear under the unit's section header.

## GEX reconfiguration workflow

1. Enable the mass storage using the LOCK button or jumper (or use the API for reading and writing the file)
2. Open the `UNITS.INI` file in a text editor
3. If adding or removing unit instances, add their names to the right type (eg. `DO=LED`), save and reload the file.
   On some systems, it's necessary to close the editor right after saving and then reopen it again after the disk
   refreshes.
4. Configure the units as needed; adjust callsigns if desired. Save and reload the file.
5. Check for error messages under unit headers. Correct any problems. Save and reload to apply any changes.
6. Push the LOCK button or replace the jumper to persist all changes to flash. If using the API, issue
   the `PERSIST_CFG` command for the same effect.

This is much easier when done through the API, perhaps using the PyQt GEX configuration utility included as an
example in the Python client repository.