Physical boards

To run AmForth on a physical board, the usual sequence is straightforward

  • make all - to build the bin or hex file
  • make upload - to upload the file to the board (this requires board specific upload tool)
  • make shell - to connect amforth-shell.py to the board (MODEM variable needs to point at the board’s serial device)

You can use any terminal emulator to connect to AmForth, but it is highly recommended to use amforth-shell.py because it provides a number of AmForth specific highly useful conveniences that will be lacking with other emulators.

amforth-shell.py

amforth-shell.py requires Python3 and the pyserial package. Python3 is often pre-installed by the host OS. If it isn’t follow the recommended installation approach for your OS. The pyserial package usually needs to be installed with pip3 install pyserial command. If this gives you error: externally-managed-environment, and you don’t want to heed its warnings and deal with Python virtual environments, then pip3 install --user --break-system-packages pyserial should be a relatively safe work-around.

Uploaders

Uploaders are highly MCU specific tools. There are no general installation instructions to offer here. The best route may be installing the recommended development environment for the board in question and finding what it is using. The MCU Makefile or readme may have some pointers. The make upload command can be used to upload AmForth binary file to the board, once the correct uploader is installed. The MCU Makefile should have instructions on how to connect the uploader installation to the make command.

QEMU

AmForth provides a number of emulated build targets. With these you do not upload AmForth binary file, instead you execute the amforth.elf file with the corresponding variant of the QEMU emulator. Use the recommended installation path for your OS to install QEMU. For ARM you will need qemu-system-arm, for RISC-V you will need qemu-system-riscv32.

There are several ways to run AmForth under QEMU, the Makefiles usually provide following options.

  • make stdio - starts AmForth connected directly to the stdio of the terminal running the command; you don’t need a terminal emulator in this case, but you only get very basic interaction capabilities
  • make pty - starts AmForth connected to a PTY device (very much like when it’s running on a physical board); the terminal stdio is connected to the QEMU monitor allowing control of the emulation process; QEMU will output the name of the PTY device on startup, set the MODEM variable to that and start amforth-shell.py with make shell

Finally the Linux based targets (e.g. arm/mcu/linux) can run on qemu-user on Linux or in Docker on other operating systems.

This site uses Just the Docs, a documentation theme for Jekyll.