Open RF Prototyping

Software Overview

The ECApp firmware is designed to provide simple, low level access to the underlying controller hardware. The controller hardware consists of the following:

• Host computer communications device. This is provided by the USB communications device class (CDC) with the ECApp firmware appearing as an RS-232 serial device on the USB host.

• Serial Peripheral Interface (SPI) and GPIO pins provide the required control access for communicating with and configuring the connected rfblocks hardware modules.

Figure 1 illustrates the overall environment.

The host computer communicates with the embedded control software using simple ASCII protocol commands. These commands are used by application level Python framework which provides a more convenient way to control the target hardware. For more details for this application software please consult Software Support section of the RF Blocks - Open RF System Prototyping document.

Command summary

The ECApp commands are summarized in Table 1. Each command starts with a single character which may then be followed by zero or more command parameters (depending on the specific command) and terminated by the ':' (colon) character.

In Table 1 command parameters are described using the following abbreviations:

<port>

This is a single character specifying a microcontroller I/O port. For the Atmega32U2 Board an I/O port is defined as a collection of up to 8 I/O pins on the microcontroller board as specified in the Atmega32U2 data sheet. For example, 'B' would indicate port PB. In the case of the Raspberry Pi Pico board, the I/O port consists of a single port 'G' with 21 pins. For the purposes of backwards compatibility Atmega32U2 type ports have also been mapped to Pico board GPIO pins.

<pin>

This is a character string specifying the port and number of a microcontroller I/O pin. For example, 'G15' indicates GPIO 15 on the Pico board (pin 20) and 'B5' would indicate pin 5 on port PB of the the Atmega32U2 board (if the Pico board is in use this is also mapped to 'G20' or pin 26).

<bytes>

This is a comma separated sequence of hex formatted ASCII byte values. An an example, the sequence of decimal numbers 12,220,78,167,9 would be: 'C,DC,4E,A7,9'.

<mask>

This is a single hex formatted ASCII byte value. For example, the mask 0b1100_0100 would be 'C4'.

<num>

A numeric string.

Command examples

In almost all cases the application level rfblocks Python package is used to interact with the ECApp controller firmware. However in some circumstances it may be useful to interact directly with the firmware. This can be done using a terminal emulator or by using the Python pySerial package.

• The following series of commands sets the frequency tuning word for the AD9913. The first command sets pin D1 low, the next command sends 5 bytes via the SPI followed by the final three commands which set pin D1 high and then briefly toggling pin D2 high.

  LD1:W03,0A,3D,70,A4:HD1:HD2:LD2:

• The following commands initialize the microcontroller pin states for communicating with the HMC833.

  OD1:LD1:IC5:W00:

  The first command sets pin D1 as an output followed by the command to set pin D1 low. The third command in the series sets pin C5 as an input. Finally, the byte 00 is sent via the SPI. (This has the effect of toggling the SPI SCK line which will put the connected HMC833 into 'open' mode.)

• The following series of commands sets the AD9552 output frequency and then checks the status of the PLL lock.

  LD2:W00,0E,74:HD2:LD2:W00,05,01:HD2:LD2:W60,19,80,39,00,00,00,FE,FF,FF,AF:HD2:LD2:W00,05,01:HD2:LD2:W00,0E,F4:HD2:LD2:W00,05,01:HD2:
  PC6:

• The following command toggles the high state on pins PB7 and PB6:

  MB,C0,00,C0,00:

For more examples of using the ECApp commands it's worth looking at the code for the rfblocks device API.

Limitations

The firmware has some limitations which arise either from the limitations of the microcontroller hardware on which it executes or compile time limits. The primary limitations are on memory buffer sizes. These are listed in Table 3.

In the case of the Pico board the limits are fairly arbitrary since the available SRAM (256kB) is much larger than the Atmega. If longer commands are anticipated then it's a simple matter of rebuilding the Pico firmware with larger values for the buffers.

Using the ECApp with Zephyr

This is a version of the ECApp embedded command processor designed for use on the Raspberry Pi Pico controller in a multithreaded environment. Figure 2 illustrates the arrangement of the components of the firmware.

• Cooperative time slicing is used as the thread scheduling algorithm.

• At it's core is the 'vanilla' command interpreter implemented by the execute_cmd function. The command interpreter runs in a separate thread - the cmd_exec_thread.

• The cmd_exec_thread receives commands from the process_cmds function running in the cmd_proc_thread via a message queue - the cmd_msgq. The execute_cmd function then parses and executes the command via a set of API functions. Access to these functions is controlled by the cmd_execution_sem semaphore.

• The cmd_proc_thread in turn waits on the availability of command characters placed in the recvbuf ring buffer by the USB serial device interrupt handler implemented in the interrupt_handler function. The process_cmds function builds complete commands and then places them on the cmd_msgq queue.

• After execution of a command completes a response can be passed back to the controlling host by placing it on the respbuf ring buffer and enabling the serial transmit interrupt.

• Application specific functionality is implemented in app_thread. The ECApp A command is provided to allow commands to be passed to the application specific thread for processing.

• The contents of application specific commands received by execute_cmd are made available to app_thread by placing them on the app_msgq queue.

• app_thread can make use of the API functions by first claiming the cmd_execution_sem semaphore.

• app_thread may also make use of the execute_cmd functionality by placing ECApp commands on the cmd_msgq queue. Responses to these would be passed back via the app_respbuf ring buffer. However, note that it is more efficient to make use of the API functions directly from within app_thread.

Source code for the Zephyr version of ECApp

Useful links to Zephyr documentation:

1. Zephyr Message Queues

2. Zephyr Threads

3. Zephyr Semaphores

4. Zephyr Cooperative Time Slicing

Building the Firmware

Check out the source code:

git clone git@gitlab.com:dyadic/ecapp.git
cd ecapp
git branch
* master

The sections below provide details for building firmware for the Raspberry Pi Pico board and the Atmega32u2.

cd pico/apps/cmdproc
mkdir build
cd build
cmake ..
make

$ cd target/build/atmega32u2
$ make TARGET=../../../src/app/usbcmd/cmdproc clean
$ make TARGET=../../../src/app/usbcmd/cmdproc   # build the target app

$ make TARGET=../../../src/app/usbcmd/cmdproc help

$ make TARGET=../../../src/app/usbcmd/cmdproc avrdude

cd ecapp/src/util/Bootloaders/DFU
make clean
make

AVRDUDE_PORT   = /dev/tty.usbserial-A600e0V2
AVRDUDE_PROGRAMMER = buspirate
AVRDUDE_FLAGS =
# To suppress flash verification after upload:
# (comment out the following to enable verification after upload)
AVRDUDE_VERIFY = -V

make avrdude

LUFA License

          LUFA Library
Copyright (C) Dean Camera, 2021.

dean [at] fourwalledcubicle [dot] com
           www.lufa-lib.org


Permission to use, copy, modify, and distribute this software
and its documentation for any purpose is hereby granted without
fee, provided that the above copyright notice appear in all
copies and that both that the copyright notice and this
permission notice and warranty disclaimer appear in supporting
documentation, and that the name of the author not be used in
advertising or publicity pertaining to distribution of the
software without specific, written prior permission.

The author disclaims all warranties with regard to this
software, including all implied warranties of merchantability
and fitness.  In no event shall the author be liable for any
special, indirect or consequential damages or any damages
whatsoever resulting from loss of use, data or profits, whether
in an action of contract, negligence or other tortious action,
arising out of or in connection with the use or performance of
this software.