This guide describes how to use the Sensor Controller Interface driver (SCIF) generated from the following Sensor Controller project:
The guide is tailored for this project, and contains code snippets that you can copy and paste directly into your application.
Sensor Controller task code cannot be debugged from the application IDE (IAR EWARM or CCS).
Use Task Testing, Task Debugging and/or Run-Time Logging in Sensor Controller Studio to make sure that your Sensor Controller task(s) work as expected, before you start integrating the SCIF driver into the application.
Follow these steps to start integrating the SCIF driver into your application:
These sections cover additional SCIF driver features and other information that can be helpful when integrating the SCIF driver:
This section describes how to add and start integrating the SCIF driver into an existing System CPU application.
It is assumed that all the code snippets below go into one C source file, in the same directory as the SCIF driver. Otherwise you may have to change #include paths, and add function prototypes.
If you do not have an existing application, please take a look at some of the examples in Sensor Controller Studio.
You must add these files to your application project:
You can optionally add these files to the application project:
Add the following code to include the SCIF driver main header file:
#include "scif.h"
Add these SCIF driver callback functions to the application:
// SCIF driver callback: Task control interface ready (non-blocking task control operation completed) void scCtrlReadyCallback(void) { }
// SCIF driver callback: Sensor Controller task code has generated an alert interrupt void scTaskAlertCallback(void) { }
Add the following code to initialize the SCIF driver. You can do this:
// Initialize the SCIF operating system abstraction layer scifOsalInit(); scifOsalRegisterCtrlReadyCallback(scCtrlReadyCallback); scifOsalRegisterTaskAlertCallback(scTaskAlertCallback); // Initialize the SCIF driver scifInit(&scifDriverSetup); // Enable RTC ticks, with N Hz tick interval scifStartRtcTicksNow(0x00010000 / N);
The scifInit() call initializes all I/O pins used by the Sensor Controller. Do not configure these I/O pins in the application.
The SCIF driver uses the task control interface to start and stop Sensor Controller tasks, and perform other task control operations. The Task Control section describes how to use the task control functions correctly, but for now we will only perform one operation that starts the Sensor Controller task.
To start the "HDC2010 Sensor" task:
// Start the "HDC2010 Sensor" Sensor Controller task scifStartTasksNbl(1 << SCIF_HDC2010_SENSOR_TASK_ID);
The application can directly access the Sensor Controller's cfg, input, output and state data structures, which are located in the AUX RAM. This is the one and only mechanism for exchanging data between the Sensor Controller and the application.
Resource-specified data structure members should not be accessed directly, but rather through the resource provided API.
The application will typically write to the cfg data structure before the task is started:
scifTaskData.hdc2010Sensor.cfg.highThreshold = ...; scifTaskData.hdc2010Sensor.cfg.lowThreshold = ...; scifTaskData.hdc2010Sensor.cfg.minReportInterval = ...;
The application will typically read from the output data structure while the task is running:
... = scifTaskData.hdc2010Sensor.output.head; ... = scifTaskData.hdc2010Sensor.output.humDecimalPct; ... = scifTaskData.hdc2010Sensor.output.humValue; for (int n = 0; n < SCIF_HDC2010_SENSOR_BUFFER_SIZE; n++) { ... = scifTaskData.hdc2010Sensor.output.pBuffer[n]; } ... = scifTaskData.hdc2010Sensor.output.tmpDecimalC; ... = scifTaskData.hdc2010Sensor.output.tmpValue;
The state data structure is normally for internal use by the Sensor Controller, but can also be used for data exchange during operation or for observation:
... = scifTaskData.hdc2010Sensor.state.samplesSinceLastReport; scifTaskData.hdc2010Sensor.state.samplesSinceLastReport = ...;
You can handle Sensor Controller ALERT events at any desired priority level, for example:
// Clear the ALERT interrupt source scifClearAlertIntSource(); ... Access Sensor Controller task data structures here ... // Acknowledge the ALERT event scifAckAlertEvents();
This section describes task control in more detail, additional SCIF driver features, and other useful information.
Task control operations are used to start and stop Sensor Controller tasks, and to trigger manual execution of task code blocks.
The task control interface can perform one operation at a time, and it is busy until the Sensor Controller has completed the operation. The task control functions are, however, non-blocking (hence the Nbl suffix), and return immediately. This means that you must wait for each task control operation to finish before performing another operation.
You can wait either before or after each task control operation. Normally it makes sense to wait before each operation since this reduces the waiting time. If your application performs task control from multiple threads of execution, you must ensure that this is done atomically:
This code waits until the previous task control operation has finished, with a timeout in microseconds. The timeout is application specific. The function returns immediately if task control interface already is ready.
// Wait with 20 millisecond timeout if (scifWaitOnNbl(20000) != SCIF_SUCCESS) { ... Handle timeout or usage error (see the function documentation) ... } else { ... Perform the next task control operation, for example start Sensor Controller tasks ... }
Starting a Sensor Controller task triggers the Initialization code. The task is then active.
After a Sensor Controller task has been stopped (see below), you must reset the task's data structures before it can be restarted. The scifResetTaskStructs() function will always reset the state data structure. You can optionally also reset the cfg, input and output data structures.
Do the following to (re)start a Sensor Controller task:
// Reset all data structures except configuration scifResetTaskStructs(1 << SCIF_HDC2010_SENSOR_TASK_ID, (1 << SCIF_STRUCT_INPUT) | (1 << SCIF_STRUCT_OUTPUT)); // (Re)start the "HDC2010 Sensor" Sensor Controller task if (scifWaitOnNbl(20000) != SCIF_SUCCESS) { ... Handle timeout or usage error ... } else if (scifStartTasksNbl(1 << SCIF_HDC2010_SENSOR_TASK_ID) != SCIF_SUCCESS) { ... Handle usage error ... }
Stopping a Sensor Controller task triggers the Termination code. The task is then inactive.
Do the following to stop a Sensor Controller task:
// Stop the "HDC2010 Sensor" Sensor Controller task if (scifWaitOnNbl(20000) != SCIF_SUCCESS) { ... Handle timeout or usage error ... } else if (scifStopTasksNbl(1 << SCIF_HDC2010_SENSOR_TASK_ID) != SCIF_SUCCESS) { ... Handle usage error ... }
Running a Sensor Controller task once triggers the Initialization Code, the Execution Code (one time), and the Termination Code.
Do the following to run a Sensor Controller task once:
// Run the "HDC2010 Sensor" Sensor Controller task if (scifWaitOnNbl(20000) != SCIF_SUCCESS) { ... Handle timeout or usage error ... } else if (scifExecuteTasksOnceNbl(1 << SCIF_HDC2010_SENSOR_TASK_ID) != SCIF_SUCCESS) { ... Handle usage error ... }
For an active task, it is possible to trigger the Execution Code manually.
Do the following to trigger a single iteration of the Execution Code:
// Run the "HDC2010 Sensor" Execution Code if (scifWaitOnNbl(20000) != SCIF_SUCCESS) { ... Handle timeout or usage error ... } else if (scifSwTriggerExecutionCodeNbl(1 << SCIF_HDC2010_SENSOR_TASK_ID) != SCIF_SUCCESS) { ... Handle usage error ... }
For an active task, it is possible to trigger the Event Handler Code manually.
This code generates event trigger index 0 for task HDC2010 Sensor:
// Generate the event trigger 0 for HDC2010 Sensor if (scifSwTriggerEventHandlerCode(SCIF_HDC2010_SENSOR_TASK_ID, 0) != SCIF_SUCCESS) { ... Handle usage error (see below) ... }
Note that this does not use the task control interface. The scifSwTriggerEventHandlerCode() call triggers code on the Sensor Controller that generates the event trigger. The function fails with return value SCIF_NOT_READY if called again before the last scifSwTriggerEventHandlerCode() operation has finished on the Sensor Controller.
In some applications you may want to transfer ownership of I/O pins between the Sensor Controller and MCU domain peripherals, for example when:
To transfer I/O pins from Sensor Controller task(s) to the application:
To transfer I/O pins from the application back to Sensor Controller tasks:
scifReinitTaskIo(1 << SCIF_HDC2010_SENSOR_TASK_ID);
The SCIF Driver provides these definitions for use in the application:
It is possible to include multiple SCIF driver setups (that is, outputs from multiple Sensor Controller projects) in one application.
To switch driver setup, first stop using and uninitialize this SCIF driver:
// Stop all Sensor Controller tasks if (scifWaitOnNbl(20000) != SCIF_SUCCESS) { ... Handle error... } else if (scifStopTasksNbl((1 << SCIF_HDC2010_SENSOR_TASK_ID)) != SCIF_SUCCESS) { ... Handle error... } else if (scifWaitOnNbl(20000) != SCIF_SUCCESS) { ... Handle error... } else { // All tasks have been stopped successfully // Disable RTC ticks scifStopRtcTicks(); // Uninitialize the SCIF driver (includes I/O configuration) scifUninit(); }
Then initialize the other SCIF driver, as described in its "How to Use" guide.
The scifUninit() call uninitializes all Sensor Controller I/O pins. The I/O pins will be reverted to regular GPIO inputs, with pull as configured in the Sensor Controller Studio task panel(s).
Use the Sensor Controller Studio command line interface (CLI) to ensure that the generated SCIF driver is up-to-date.
The -s parameter prevents file output when existing files already are up-to-date.
"C:\Program Files (x86)\Texas Instruments\Sensor Controller Studio\bin\sensor_controller_studio_cli.exe" -g "C:/Users/a0797195/workspace_v92/CC1352P1_SCE_BASSENSORS/sce/HDC2010_TMP116_CC1352P_I2C_PullUpOff.scp" -s -q
"C:/Program Files (x86)/Texas Instruments/Sensor Controller Studio/bin/sensor_controller_studio_cli.exe" -g "C:/Users/a0797195/workspace_v92/CC1352P1_SCE_BASSENSORS/sce/HDC2010_TMP116_CC1352P_I2C_PullUpOff.scp" -s -q
Doxygen generates HTML documentation based on specially formatted comments in source code. Download Doxygen from http://www.doxygen.org/.
Set the path to doxygen.exe in the Preferences panel if needed. The current path is C:/Program Files/doxygen/bin/doxygen.exe.
To create or update the HTML documentation, run scif_run_doxygen.bat. The generated documentation can then be found here: scif_dox/index.html