Parameter Tuning and Signal Logging with Serial External Mode
This example shows how to perform parameter tuning and data logging with a Simulink® model running in External mode on the Texas Instruments™ C2000 targets. See Embedded Coder Support Package for Texas Instruments C2000 Processors for details on workflows for Texas Instruments C2000 Processors.
- Any of the Texas Instruments C2000 based controlCARDS with docking station or Spectrum Digital eZdsp boards that have serial interface with SCI_A.
Note: F281x based boards are not supported with serial External mode. Refer to CAN based External mode for these boards.
- A USB serial cable, if your hardware provides serial over USB capabilities or an RS-232 cable connected to the COM1 port of your computer.
The following figure shows the example model.
In this example, you will learn how to configure a Simulink model to run in External mode, perform parameter tuning and explore the different options available to log data.
Configure the hardware and model for External mode
Set up the hardware
This demo uses Texas Instruments F28335 ControlCARD with docking station. In this example, we use the USB serial cable to establish a serial connection between the host computer and the target hardware. You can also use the COM1 port of your computer to establish an RS-232 serial connection with the board. See Set Up Serial Communication with Target Hardware for details on establishing a serial connection between the target and the host computer.
After establishing a serial connection, find the COM port associated with the target hardware.
- Open Device Manager in Windows.
- Expand the Ports Tab.
- Note down the COM port associated with the target board.
Set up the model
The Example Model is configured for the target hardware Texas Instruments F28335 ControlCARD with docking station. You can follow the procedure given below for any other hardware board mentioned in the Required hardware section. See also External mode over Serial Communication for details on External mode over serial communication for Texas Instruments C2000 Processors.
1. Open the Example Model.
2. Open Model Configuration Parameters and navigate to the Hardware Implementation pane.
3. Select your target hardware from the Hardware board drop-down list.
Note: To run the Example Model on targets with small RAM such as F28027 and F28035, enable the Boot From Flash (stand alone execution) option in Hardware Implementation > Target Hardware Resources > Build options tab and increase the heap size as mentioned in the Limitations section. Texas Instruments Code Composer Studio v3.3 is not supported with serial External mode.
4. Navigate to the Hardware Implementation > Target Hardware Resources > External mode. Specify the Communication interface as serial. Specify the Serial port with the COM port number associated with your target hardware. The Verbose option enables viewing the execution progress of the External mode simulation on the Diagnostic Viewer and on the MATLAB Command Window. Navigate to SCI_A and specify the baud rate in Desired baud rate in bits/sec. The default baud rate value is 115200.
5. Navigate to the Code Generation pane and select the Toolchain to match the version of Texas Instruments Code Composer Studio installed on your computer.
6. Select External from the Simulation mode drop-down list in the Simulink Editor Window and specify a desired value for stop time. You can specify the stop time as 'inf' to run the model continuously on the target hardware.
Task 1 : Run the model in External mode
When running a model in External mode, the host computer communicates with the target, on which the generated executable runs. To run the Example Model in External mode:
1. Press the Run button in the Simulink Editor. You can observe from the Diagnostic Viewer that the code is generated for the model and the host connects to the target after loading the generated executable.
2. While the model is running in External mode, open the Scope connected to the Gain block to monitor its output.
3. Press the Stop button in the Simulink Editor to terminate the External mode simulation.
Task 2 : Parameter Tuning
Simulink External mode enables tuning parameter values while the generated executable is running on the target hardware. When the parameter values are changed in the Simulink model, the modified values are communicated to the target hardware.
1. Run the model in External mode.
2. When the model is running, double click on the Gain block and change the value of the gain. You can observe that the amplitude of the sine waveform has changed according to the new gain value. Change the value of the Constant block to '0' in order to switch the input source and observe the result on the Scope. If the option Verbose is selected in the Model Configuration Parameters > Hardware Implementation > External mode, the status of the parameter change is displayed on the MATLAB Command Window.
3. Stop External mode simulation.
To modify more than one parameter and communicate the changes to the target hardware at once, use the Batch download option in the External Mode Control Panel. To open the External Mode Control Panel, go to the Code menu in the Simulink Editor and select External Mode Control Panel. Refer to Parameter Downloading for details on the Batch Download option.
Task 3 : Data Logging
To log data from the External mode simulation of a model to a file, you can either make use of the Scope or the To Workspace block. Follow the steps below to manually trigger data logging or trigger data logging from a signal.
Logging signals with a manual trigger
You can use the Arm trigger button on the External Mode Control Panel to trigger data logging. The Arm when connecting to target option enables the trigger automatically when the host connects to the target and data uploading begins. Otherwise, to start uploading the data, you must manually arm the trigger by clicking the Arm trigger button located in the External Mode Control Panel. Triggers can be useful when the communication channel speed does not allow live visualization of the desired signals. In this task, you will learn how to manually trigger data uploading from the target to the host computer.
1. Open the External Mode Control Panel and click on the Signal & Triggering button, which opens the External Signal & Triggering dialog box.
a. By default, the Source option is set to manual. Set the Mode to normal to collect contiguous data samples. External mode allocates sufficient memory to collect data for the length of the Duration for each signal. Depending on the communication speed and the processing time given to the External mode engine that is running as a background task, you may see a continuous data logging stream, or a stream of data containing gaps corresponding to the time required to send the acquired buffers.
b. Specify the Duration as '15' to collect 15 data samples for a base rate signal. Since the signal from the Gain block has the same sample rate as that of the model, the number of samples collected in each data set is 15. Uncheck the Arm when connecting to target option for enabling manual trigger to upload data.
2. To view the sample time of the model, navigate to Display > Sample Time and select Sample Time Legend. For this example model, you can observe that the sample time is 0.01 s.
3. Click on the Data Archiving button of the External Mode Control Panel to enable the logging of data to a MAT file via the Enable Data Archiving dialog box.
4. Check the Enable Archiving option. Use the File and Directory parameters to specify the destination of your log file. In normal mode, file name incrementing happens automatically and new data sets are saved in new MAT files.
5. Open the Scope connected to the Gain block and click on the Configuration Properties button. Navigate to the Logging tab and check the Log data to workspace option. Specify a name in Variable name. The logged data is saved in this variable. In order to save the time instant and the signal data values, select the Save format as Structure with time.
Note: If you do not select the Save data to workspace option, the MAT-files for data logging are created, but they will be empty.
6. Run the model in External mode by clicking on the Run button. Press the Arm Trigger button on the External Mode Control Panel to trigger data logging and the Cancel Trigger button to stop logging the data. Navigate to the folder specified for saving the logged data. You can observe that several MAT files are created, each containing a structure with 15 contiguous data samples.
7. Press the Stop button in the Simulink Editor to terminate the External mode simulation.
To collect only a single set of contiguous data samples, choose the Mode as One-shot. In this mode, check the option Increment file after one-shot in the Enable Data Archiving dialog box to save new data sets in new MAT files.
Logging signal data using a signal trigger
In signal trigger mode, External mode is directed to use a signal as a trigger to start logging data. The data uploading begins when the trigger event occurs. To analyze a signal when an error or fault condition occurs while the model is running in External mode, use a signal trigger to log data.
In this task, you will learn how to trigger data logging to a file when certain signal conditions are met. In signal trigger mode, depending on the Delay specified, you can choose to log data samples of a signal immediately at trigger, a few seconds after the occurrence of the trigger, or both before and after the occurrence of the trigger.
1. Open the External Signal & Triggering dialog box from the External Mode Control Panel.
2. In this dialog box, select the Scope block connected to the Step input and click on the Trigger Signal button to make the selected block signal as the trigger signal.
a. Select the trigger Source as signal. This enables the options in the section Trigger signal to specify the trigger conditions. Set the Mode to normal to collect contiguous data samples.
b. Specify the Duration as 15 to collect 15 base rate samples whenever the trigger conditions are satisfied.
c. Specify the Delay as 5. This would cause data logging to begin 5 base rate samples after the occurence of the signal trigger. As the sample time for this model is 0.01 s and the step input is applied at the time instant 26 s, data logging begins from the time instant 26.05 s , (i.e 5 * 0.01 s after the trigger event at 26 s).
d. In the Trigger signal section, choose the Direction as rising and the Level as '1'. This causes the signal trigger conditions to be met whenever the signal connected to Scope1 increases in magnitude and crosses the threshold value of '1'.
3. As mentioned in the task Logging signals with a manual trigger, specify a folder and a file name in the Enable Data Archiving dialog box to save the logged data.
4. Run the model in External mode.
5. As the trigger conditions are met at the time instant 26 s, stop the External mode simulation after, say 40 s. Navigate to the folder where the data is saved and load the MAT file into MATLAB workspace by double-clicking on it. If you examine the contents of the MAT file, you can observe from the structure member 'time', that data is logged from the time instant 26.05 s, i.e 5 base rate samples after the trigger conditions are met.
If the Delay is specified as '0', logging of the signal data would begin immediately when the signal trigger conditions are met. The Delay option can be used with negative values to center the data acquisition around the event of interest. To log data samples before the trigger conditions occur for the Example Model, specify a negative value, say '-8' in the Delay field. This captures 8 base rate samples before the occurrence of trigger and the remaining data samples after the occurrence of trigger.
To collect a data set of base rate samples only when the signal trigger conditions are met for the first time, choose the Mode as One Shot. This mode is useful for viewing fast changing data on a slow communication channel. To achieve this, increase the value of the Duration and set the signal trigger to acquire relevant data based on an event of interest, like a fault signal, an over voltage/current signal, a temperature warning signal etc.
1. Increasing the Duration allows the capture of large real-time buffers. These buffers use heap section to allocate memory. A high value of Duration may result in Not enough memory on the target to process the packet warning, and consequently cause no data to be uploaded from the target to the host computer. To overcome this warning, specify a larger heap size if your target has sufficient memory. To change the heap size, go to the Model Configuration Parameters > Code Generation > Build Configuration > Specify and modify the value for the option '--heap_size'.
2. Parameter tuning and signal logging for 8-bit data types is not supported over serial External mode for Texas Instruments C2000 processors. See Data Type Support for details on the data type support for Texas Instruments C2000 processors.
1. An error stating 'Attempting to establish connection with hostname 127.0.0.1 through port ...' indicates that either the COM port or the TCP/IP port 17725 on the local loopback are held by some other application. Make sure they are available before launching external mode. External mode uses a process in the background to buffer data and improve data logging. This process needs port 17725.
2. If you observe breaks in the scope you can try the following to improve logging:
a. Increase Serial Baud Rate
b. Decrease the number of signals selected for logging
c. Decrease the model base rate
This example introduced the workflow for parameter tuning and data logging for External mode simulations on a Texas Instruments C2000 target hardware over a serial communication channel.