UART Terminal Example

 Objective

This Simulink® model implements a terminal user interface on the targeted dsPIC® Digital Signal Controllers (DSCs) to display selected information (CPU load/overload, temperature, elapsed time, CPU and compiler information). A UART terminal emulator (Tera Term, RealTerm, PuTTY …) serves as the interface on the PC side. The example demonstrates an original use case of the UART and C-Function Call blocks used to process character strings which are not natively handled by Simulink. The added C function is simple. The CPU load information displayed relies on the block's CPU load and overload, which are briefly presented.
The example targets the Explorer 16/32 with a dsPIC33EP512MU810 PIM and could be adapted for various boards. The ZIP file with the example includes a version adapted for the Microstick II with Microstick Plus Development Board (see the "Hardware Setup" section for further details).

UartTerminalModel.PNG
Click image to enlarge.
Simulink UART terminal model

 Materials

Hardware Tools

Tool About Purchase
Explorer16-50px.png
Explorer 16
Development Board
Explorer1632-50px.png
Explorer 16/32
Development Board
hwtool-50px.png
dsPIC33EP512MU810 PIM
Explorer13/32 PIM
hwtool-50px.png
Microstick II
Microstick II
hwtool-50px.png
Microstick Plus Development Board
Microstick Plus Development Board

Hardware setup

Explorer1632_Setup2.jpg
Explorer 16/32 setup
USB cable on J18 (PKOB) to program the board.
USB cable on J40 (embedded USB to serial) to send/receive UART data to/from your Terminal.

Software Tools

This project works with software tools:

  • MPLAB® Device Blocks for Simulink v3.40,
  • MPLAB® XC16 Compiler v1.33,
  • MPLAB®X IDE v4.10, and
  • MATLAB R2014b or newer.

A UART terminal that supports VT-100 protocol should run on a host computer (e.g., Terra Term, PuTTY or Realterm).

The tools can be found on the following Microchip websites:
MPLAB® Device Blocks for Simulink
MPLAB® XC16 Compiler
MPLAB®X IDE

For the installation procedure and tools required, check the MPLAB® Device Blocks for Simulink Installation section.

Exercise Files

Do not use from the ZIP file. Extract ZIP file then from MATLAB, go to that working folder.
Download the project file corresponding to your development board.

File Download
Installation
Instructions
Windows Linux Mac OSX
UART Terminal Project

 Procedure

The following steps provide the instructions on how to use the projects.

1

Extract the downloaded ZIP file and then open the model file in Simulink. Make sure that the hardware is connected and properly set up as shown in the "Hardware Setup" section.

2

Select your integrated programmer device. Select MICROCHIP > Selected Programmer > "Programmer - Name". If your programmer is not listed, click Refresh list and select it following the same procedure. Make sure that the option to flash the device after the build is enabled (MICROCHIP> Flash after build).

UartTerminalModel-ProgrammerSelect.PNG
Programmer selection and Flash after Build option

3

Press the Build button and wait for the process to complete.

UartTerminalModel-BuildAndFlashPNG.PNG
Build and Flash

4

Launch your terminal emulator.
In the terminal program, open the COM port associated with your development board (some terminals show a list of COM ports available). Use the following setup:
- Baud Rate: 115200
- Data: 8 bits
- Parity bit: none
- Stop bit: 1 bit

Note: Most terminals detect VT-100 protocol automatically. RealTerm V3 and above need to manually activate VT-100 in the display tab.

 Results

TerminalMenu.PNG
UART terminal menu (help) is displayed on terminal once connected.

Terminal user interface

The compiled model sends the help menu every 2 s until a valid command is typed. The menu appears on the terminal within 2 s of its connection. This 2 s refresh is stopped for 10 s each time a character is received on the UART so as not interfere with a command being typed. Once a valid command is received, the system knows that a terminal is already connected, and this refresh mechanism is switched off.

Controls

ESC - erase current line of text
BASKSPACE - delete one character
ENTER - validate a command
An error message appears when an invalid command is received.

Commands

"help" - displays a list of available commands and control keys.
"clear" - clears the entire screen
"info" - displays various information about device and compiler.
"cpu" - displays the current CPU load. (see Potentiometer action on load)

Potentiometer

"onboard Potentiometer" - increases/decreases a synthetic load which can mimic a calculation. An overload appears when the synthetic load exceeds the time step period it belongs to. The block “Tasking” controls the behavior of the model on overload (beyond the scope of this example).

"temp" - displays the temperature of the onboard analog sensor.

"time" - shows how long the model has been running. However, if an overload occurs, the elapsed time estimation is not underestimating the time because the real-time constraint of the model is violated.

 Analysis

UartTerminalModel.PNG
UART Terminal Model overview

Model description

The housekeeping subsystem block (“Explorer 16/32 - dsPIC33EP512MU810” in this example) contains all blocks required to set up the Simulink model for code generation for a dsPIC device. The most important are: Microchip Master (to configure the dsPIC device), Compiler Options (XC16 compiler configuration), and UART Configuration (peripheral used to communicate with the terminal).

A code.c file is added to the model code generation file list (Model Configuration Parameters > Code Generation > Custom code tab). It contains user functions to manage operations on strings, which include buffering of user input and matching with pre-defined commands.

Functions in code.c are used within the Terminal Interface Management subsystem through a C Function Call block. For every key press, this block (c-function) returns an 8-bit value coding for the action to be taken (e.g., return value 2 is issued when the ESC key is pressed). The values returned are categorized into two groups: terminal management (return values 0/1/2) or command actions (10…15). Check the code.c file for further details.

When a valid command is issued, the Menu Display Selection, a switch-case block executes a subsystem corresponding to the action.

The Data Collector subsystem contains blocks providing CPU Load/Overload and ADC readings for temperature sensor/potentiometer. The CPU Load block uses a timer to measure the effective busy time. You can select the maximum period to be measured within the block GUI at the expense of reduced resolution. The CPU load block is set with a max period of 240 ms which provides a measurement resolution of 3.66us. The CPU load measurement returns the CPU load time between the two last starts of the task (i.e., sample time) the block belongs to. The CPU load block sampling time is set to 200 ms. Its output could overflow if the CPU load measured gets above 120% (corresponding to 240 ms). One consequence of an overload is that tasks get delayed which explains why the CPU load block output value might get higher than its own sampling time. Note, however, that a CPU load lower than 100% does not mean that another task has not overloaded the CPU and violated real-time constraints. The CPU Overload block must be used to detect any overload.

The CPU Overload block's output is zero when no overload has occurred between the two last consecutive tasks (i.e., sample time) that the Overload block belongs to. If an overload occurs, the output bit corresponding to the task thread IDs (TIDs) which overloads at least once is set to one. Thus, the output is different from zero on any overload.

The ADC block is configured to convert two analog inputs (Temperature sensor and Potentiometer) with 10 bits resolution using the parallel sample and hold peripheral capabilities. Sixty-four samples are converted for each channel at each time step, which allows for increased resolution and lowers the noise once averaged. Please note that the output impedance of the temperature sensor is high, thus using dedicated ADC channels provides better results than successively scanning ADC channels inputs.

The Time Counter subsystem provides the time elapsed since model execution started (Days:Hours:Minutes:Sec format). This time is not accurate if CPU overload occurs as a consequence of a real-time constraints violation.

Delay_us C function call block induces a variable delay with the value specified by SyntheticLoad to stress out the CPU. Using the potentiometer, it is possible to vary the CPU load and create an overload to see its consequences.

“Snake LED” toggles the LEDs on the board. The Snake LED's pattern provides a visual indicator that the model is running, and possibly overloaded (slower snake).

 Conclusions

This example presented a Terminal-based user interface implemented on a dsPIC from a Simulink model. It uses UART, C Function Call blocks and few CPU profiling blocks. It could be helpful for the debugging process, execution time profiling, CPU load measurement, as well as sending and receiving external commands.

© 2019 Microchip Technology, Inc.
Notice: ARM and Cortex are the registered trademarks of ARM Limited in the EU and other countries.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.