MOWE Firmware - OUWECAD/MOWE GitHub Wiki

##Table of Contents

AOS Firmware

AOS+FreeRTOS

AOS Firmware

There are two versions of MOWE firmware. The old one, called AOS, is not based on a real-time operating system (RTOS) and is hosted in the folder Firmware/No RTOS. The AOS firmware is more comprehensive, having more CLP commands and inter-array communication routines. However, it is poor in multitasking and multithreading. Default baudrate for AOS firmware is 115200. Below is a detailed description of this version.

Firmware Overview

MOWE firmware is written in embedded C (C99) language using Keil uVision 5 IDE. The firmware is separated into four layers detailed in the following figure:

  • Hardware Abstraction Layer (HAL) Drivers: The HAL library is provided by ST and ARM and provides many APIs and low level access to the Cortex-M0 core and STM32F0xx MCU peripherals. The version used is (V1.2.1) and can be downloaded from here. Note that ST no longer provides HAL drivers as a stand-alone installation, rather you have to download the STM32CubeF0 library, which contains HAL drivers as well as RTOS and some middleware and board examples. You can also download the STM32CubeMX, which is a useful software utility to graphically configure MCU clock and peripherals. (You do not need the later one if you are using our firmware.)
  • Array Operating System (AOS): AOS is a middle layer between HAL and user application. It handles all array and module house-keeping functionality as well as the command line parser (CLP) utility. AOS has four modules on its own:
  • Peripheral Drivers (PDs): Those files were initially generated by the STM32CubeMX utility and later modified to provide higher abstraction layer for MCU peripherals.
  • Module Drivers (MDs): Provide routines for various module functionality, e.g., front-end routines, module and array parameters, etc.
  • Inter-array Communication (IAC): Provides routines to handle all inter-array (intra-module) communication needs such as single-casting (routing), multicasting and broadcasting.
  • Command Line Parser (CLP): It handles and processes all user commands.
  • Local Apps.: Contains all application-level routines running locally on the module, including the main.c file and any user applications.
  • Distributed Apps.: This section is intended for user applications that run in a distributed manner, i.e., on multiple modules simultaneously.

Firmware Overview

For a list of all firmware routines and their functionality and status, please check this page. There are multiple methods to update module firmware, ranging from basic in-application programming (IAP) to real-time debugging. A step-by-step guide can be found here.

Compiling with Keil uVision

Keil uVision is a powerful ARM development IDE. You can download an evaluation version here by choosing MDK-ARM. Please note that the evaluation version is locked to 32kb code size and cannot compile or debug current MOWE firmware with all its features enabled. You can still view all the files, however. Alternatively, you can use a lower-end, free ARM compiler and IDE like CooCox CoIDE. Follow these steps to compile the project in uVision successfully:

  1. Download latest release from the GitHub repository here.
  2. You will find firmware source code and uVision project files inside the folder Firmware.
  3. Rename the file MOWE_ProjectX.uvprojx to any other name and double click to open in uVision.
  4. Create your topology.h file yourself or generate it using MOWE ATG and copy it into the folder Firmware/AOS.
  5. Right click the file AOS.h in Windows to edit it and replace the directive #include "topology.h" with your own topology header file.
  6. Click compile in uVision and your code should compile without errors.

uVision and most other development IDEs allow you to define different targets to compile the firmware for. These targets are very useful to automatically compile the same firmware for all your array modules. (Each firmware file will be customized according to the module part number defined in the topology header file.) To add or delete a new target in uVision click Project >> Manage >> Project Items. In the Project Targets list, add or delete a new target, e.g., Module 2, and click OK. You can name the target anything you want but it is recommended to use the sequential naming scheme used in topology header file, i.e., Module 1, Module 2, etc. Once you add a new target you have to make the following modifications in the Options for Target section:

  1. In the Target tab, change the Name of Executable to match the new target name and make sure Create HEX File is enabled if you want to update firmware via module serial ports.
  2. In the C/C++ tab, add a semicolon and the sequential module name preceded by underscore, e.g., ,_module_2, to the Preprocessor Symbols define. You can chose the compiler optimization level in this tab too. It is better to use Level 1 optimization or lower if you plan to debug the code.

Using the Batch Build command in uVision you can compile firmware for all your modules (or selected ones) in one click. When you compile multiple targets at once, it is always better to choose Rebuild instead of the Build command to make sure all recent code changes have been captured in the compiled firmware. If you want to compile in different ARM IDEs such as IAR, CooCox, and others, make sure to add the module identification symbol _module_i to preprocessor defines.

Command Line Parser (CLP) commands can be enabled or disabled individually in the firmware build. This feature helps making the firmware size smaller by disabling unneeded commands. Especially if you are using the evaluation version of uVision. Compiling with all commands generates currently about 45kb code size. To enable/disable individual commands, open the file aos_clp.c and open the tab Configuration Wizard where you use checkboxes to enable/disable the commands and changes will show up automatically in the source file. Then, save and compile the project again. The Configuration Wizard is a particular feature of uVision. If you are using another compiler, you can directly modify the commands directives in the source file.

Array Operating System

The array operating system (AOS) is responsible about all the background work in the array, regarding communication, identification, and hardware drivers. For the time being, the AOS is not an RTOS. It is simply a collection of routines that the user execute indefinitely in the super loop. These routines are grouped within two callback functions: checkUser(), which is responsible about detecting and processing user input and mesDispatch(), which is responsible about releasing all communication messages to the user and performing some other tasks.

In order to incorporate and run the AOS within your firmware, three steps have to be followed:

  1. Include the main header file aos.h. This file includes ST HAL library main header file too.
  2. Run AOS initialization function AOS_init() before your super loop. This function configures MCU clock and other peripherals as well.
  3. Run AOS core AOS_run() inside your super loop

The following table lists some numbers and measurements about firmware performance.

Parameter Value Conditions
Maximum DMA streaming speed 3 Mbps MCU SYSCLK = 48000000 Hz, USART Baudrate = 6000000, USART oversampling by 8
Maximum sampling speed using read command 1000 sample/second USART Baudrate = 115200
2000 sample/second USART Baudrate = 921600
3000 sample/second USART Baudrate = 2000000
AOS_run() minimum execution time 6.66 uSec (~150 KHz) No executed commands

Command Line Parser

The command line parser (CLP) processes user input from a serial terminal and executes various commands. The commands are used to adjust module and array parameters, test the module, stream in/out at specific rates, stream using DMAs, update firmware, etc. Developers can enable or disable specific commands in their firmware compilation. Please check Compiling with Keil uVision for more details. For information about connecting to the CLP, please check the Setup and Connection wiki. Here are some quick facts about CLP:

  • All commands and their parameters are lowercase.
  • Type help to get a list of available commands in this firmware compilation.
  • Type info to get module and array information such as array topology, module ports and DMAs status, firmware version and compile date.
  • Type status to get the ports and DMAs status in the current module (which port is streaming and which DMA channel is used).
  • Use CTRL+z to cycle through the last five commands.
  • Modules are given unique IDs in the form #xxx where xxx takes sequential values from 001 to 999.
  • Each module can be named with an alias (9 characters long). You may use the alias wherever the module ID is used.
  • All module IDs and aliases are checked against a database. If they are wrong the message Wrong syntax! Please check the user manual. is displayed.
  • All commands are checked for syntax and if they are wrong the message Unknown command! is displayed.
  • All command parameters are checked for syntax and if they are wrong the message Wrong syntax! Please check the user manual. is displayed. In some commands, more detailed error messages are displayed.
  • Some commands are nonspecific, i.e., they work on both transmitter and receiver modules, while others are front-end-specific that work only on a single type of modules.
  • All commands have Target IDentifiers (TIDs) that specify which modules the command targets. For now, there are four TIDs but not all of them are supported in every command:
    • The module ID in the form #xxx.
    • The module alias.
    • The keyword me which means the current module.
    • The keyword all which means all possible modules. When a command is front-end-specific, the keyword all means all transmitters or all receivers.

A detailed list of all CLP commands and their coefficients can be found here.

Direct Memory Access Streams

The AOS provides access to multiple DMA streams. They differ in properties and share the available DMA channels on the STM32F091 MCU. This section provides all needed information to manage and use these streams. Note that once a DMA channel is used in one of the streams, it cannot be used for another one.

Available streams include:

  • Port to front-end and front-end to port DMA streams: A single stream with the following properties.
Stream DMA Channel Trigger (baudrate) Direction Data Alignment (MEM,PER) Mode ISR
TX DMA2_Channel2 UART RX (921600) PER > MEM Byte, Byte Circular Yes
RX DMA2_Channel1 UART TX (921600) MEM > PER Byte, Byte Circular No

  • Memory to front-end and front-end to memory DMA streams: Not implemented.

  • Port to memory DMA streams: Six streams with the following properties. Each stream can transfer a specific amount of bytes to a specific memory address.

Stream DMA Channel Trigger (baudrate) Direction Data Alignment (MEM,PER) Mode ISR
1 DMA1_Channel1 UART RX (115200) PER > MEM Byte, Byte Circular Yes
2 DMA1_Channel3 UART RX (115200) PER > MEM Byte, Byte Circular Yes
3 DMA1_Channel5 UART RX (115200) PER > MEM Byte, Byte Circular Yes
4 DMA1_Channel6 UART RX (115200) PER > MEM Byte, Byte Circular Yes
5 DMA2_Channel2 UART RX (115200) PER > MEM Byte, Byte Circular Yes
6 DMA2_Channel3 UART RX (115200) PER > MEM Byte, Byte Circular Yes
  • Port to port DMA streams: Six streams with the following properties.
Stream DMA Channel Trigger (baudrate source/destination) Direction Data Alignment (MEM,PER) Mode ISR
1 DMA1_Channel1 UART RX (921600/921600) PER > MEM Byte, Byte Circular No
2 DMA1_Channel3 UART RX (921600/921600) PER > MEM Byte, Byte Circular No
3 DMA1_Channel5 UART RX (921600/921600) PER > MEM Byte, Byte Circular No
4 DMA1_Channel6 UART RX (921600/921600) PER > MEM Byte, Byte Circular No
5 DMA2_Channel2 UART RX (921600/921600) PER > MEM Byte, Byte Circular No
6 DMA2_Channel3 UART RX (921600/921600) PER > MEM Byte, Byte Circular No

AOS+FreeRTOS Firmware

The new version of MOWE firmware is called AOS+FreeRTOS and is based on the famous open-source real-time operating system FreeRTOS. The used FreeRTOS version is V8.2.1. This firmware also makes use of a modified version of the command line interface (CLI) module provided by FreeRTOS to facilitate user interaction (replacing the old CLP). The AOS+FreeRTOS firmware is hosted in the folder Firmware/RTOS. Default baudrate for AOS firmware is 3000000.

RTOS Threads

The AOS+FreeRTOS firmware defines 8 threads or tasks (7 in case of pentagons):

  • The DefaultTask: can be used for signaling.

  • Port tasks (P1Task, P2Task, P3Task, P4Task, P5Task and P6Task): used to handle communication through ports.

  • The FrontEndTask: can be used to run user programs and is given a higher priority.

Note that default version of the AOS+FreeRTOS does not use DMAs. However, many of the available projects that use AOS+FreeRTOS define and use DMAs for various applications.

Available CLI Commands

Command Use Description Shortcut Status
help help List available commands. (No parameters) - Ready
run-time-stats run-time-stats Display a table showing how much processing time each FreeRTOS task has used. (No parameters) - Ready
run-stats run-stats Display a table showing the state of each FreeRTOS task. (No parameters) - Ready
ping ping Ping a module. (1 parameter) - Ready
sample sample Sample a receiver module. (1 parameter) - Ready
update update Put the module in bootloader mode to update its firmware. (1 parameter) - Ready

Notes:

  • Press enter to re-execute the last command.

  • Do not activate Half Duplex and newLine mode in RealTerm. The CLI firmware will automatically echo typed characters

  • You can put RealTerm in Ansi mode and use the backspace key to delete and correct previous characters.

  • Many projects define their own additional commands to setup parameters or run specific demos.

  • In the current AOS+FreeRTOS version, CLI commands are only executed locally and cannot execute on remote modules.

  • You need to include the identifier me in some commands but it's currently not processed. Please check the code details in the file aos_cli.c.