TM
Freescale, the Freescale logo and CodeWarrior are
trademarks of Freescale Semiconductor, Inc., Reg.
U.S. Pat. & Tm. Off. Xtrinsic is a trademark of
Freescale Semiconductor, Inc.
All other product or service names are the property
of their respective owners.
© 2013 Freescale Semiconductor, Inc.
TM
2
Objectives
In this module, there are three primary objectives focused
on delving deeper into the functionalities enabled by ISF.
• You will become familiar with the process of including
and excluding ISF components in your ISF application.
• You will gain a high-level understanding of the ISF
header files and how to use them in ISF applications.
• You will become familiar with the use of the ISF
Command Interpreter to execute functions and retrieve
sensor data via host commands to the FXLC95000
instead of modifying the inputs and outputs via the
mailboxes. This can be done directly through two
distinct paradigms:
— Command/Response
— Quick-Read.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
3
Prerequisites
To complete this module, you will need a Xtrinsic ISF 1.1 Windows 7 development PC
meeting the following minimum hardware requirements:
• Pentium 4 or newer
• 4 GB of RAM
• 2 USB ports (1.0, 2.0, or 3.0)
The development PC must have an internet connection and have specific software
installed.
1. CodeWarrior 10.5 or newer (with ColdFire support)
2. FSL_MQX_3.7_FXLC95K
3. ISF 1.1 Core Library
For more information on these installations, refer to Module 1—Installing Necessary
Software.
You will also need the following items:
• KITFXLC95000EVM/MAG/10-AXIS (Application Board and USB cables)
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
4
Prerequisites
Prior to beginning, you should have completed previous Xtrinsic ISF 1.1
Training modules.
• Module 2—Installing an ISF Binary
• Module 3—Building an ISF Binary
• Module 4—Modifying an ISF Application
Also, you should be familiar with C language programming.
Related documentation can be found on the Windows Start Icon under
“All Programs/Freescale/Xtrinsic ISF v1.1/Documentation”
or
the Detailed documentation can also be found on the Xtrinsic ISF webpage.
• ISF Software Reference Manual (ISF1P195K_SW_REFERENCE_RM)
• ISF API Reference Manual (ISF1P195K_API_REFERENCE_RM)
• ISF Software Release Notes (ISF1P195K_CORE_LIB_RELEASE_RN)
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
5
Required Items
Prior to beginning, two files must be located in the ISF 1.1
installation.
1. Go to the Windows Start Icon, select “All Programs -> Freescale
-> Xtrinsic ISF v1.1 -> Example Applications Folder”. Locate the
GetAccelData directory.
2. Go to the Windows Start Icon, select “All Programs ->
FXLC95000 Mailbox Tool -> FXLC95000 Mailbox Tool .
Alternatively, if the ISF 1.1 installer has NOT been run, these items must be downloaded
from the Xtrinsic ISF Downloads webpage.
• Download the ISF1P195K GETACCELDATA zip file from the ISF webpage
Run-time Software\Specific Applications - Apps area.
• Download the FXLC95000_ISF1P1_WIN_MAILBOX_TOOL_EXE executable file from
the Software Development Tools\Debuggers and Runtime Analysis area.
This is the Intelligent Sensor Mailbox Tool, used for transferring binaries to the
FXLC95000. (Note that it is also used for transferring commands and data between
the PC and FXLC95000.)
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
6
Overview
With your current understanding, any change to the data configuration of the
mailboxes requires modifying, rebuilding and reloading the user application,
as demonstrated in the previous module.
What if there was a simple command made from the host to read/write the
sensor data whenever and however the host needs it?
Host
User App
Commands/
Data
Internal
Sensor
Sensor
Manager
Sensor
Abstraction
ISFCommand
Interpreter
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
7
Overview (continued)
The ISF Command Interpreter (CI) provides the necessary
infrastructure to handle the dispatching of commands received via
the mailboxes. The Command Interpreter provides a general
mechanism to process commands and data read from the
mailboxes triggering the execution of the command in the user
application.
To help you understand the Command Interpreter and begin using it,
this module provides information in three main areas:
• Adding the Command Interpreter component to the project
• Understanding Command/Response operations and adding a
host command
• Understanding Quick-Read operations and implementing a QR
command to configure the Quick-Read mailboxes.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
8
The ISF Command Interpreter Component
Because ISF is provided as a set of libraries, the user has the option to link only
those components needed for their user application. The Command Interpreter (CI)
is an optional component. When included in the build, all functions provided by the
CI may be used by the user application. The same is true for any of the other ISF
components and the corresponding tasks apply.
To communicate using the CI, the host and the user applications may use one or
both of two different mechanisms.
• The CI provides a way for user applications to run synchronized commands
based upon the needs of the host application. The sensor data is provided via
the mailboxes. This is the Command/Response operation.
• The CI provides a general mechanism for user applications to write to specific
mailboxes which the host can read asynchronously. This is without the need for
the host application to issue multiple commands to read data from the
mailboxes. This is the Quick-Read operation.
Note: API documentation for all functions provided by the CI can be found in the
ISF API Reference Manual (ISF1P195K_API_REFERENCE_RM)
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
9
Import the Project
1. Open CodeWarrior.
2. Create a clean workspace.
In the Select a workspace window, click Browse, then, in a convenient location, create a
new folder named workspace_module5, then select the folder, and then click OK.
This folder is referred to as the workspace folder.
3. The material is located in the installation directory
C:\Program Files\Freescale\ISF_R1p1\Example Applications\GetAccelData
but you don’t want to corrupt the working versions with the training sandbox. As a result,
please copy the directory into the workspace_module5 directory.)
3. Navigate to the workspace5 folder, and then to the GetAccelData\Build folder.
4. Import the project into the CodeWarrior workspace.
1. Import project
2. Modify application
3. Build application
4. Connect hardware
5. Configure connection
6. Establishcommunication
7. Run application
8. TestModule 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
10
Add CI Component to the Project
There are two sets of header files used in ISF.
• Header files associated with ISF are located in the ISF_ROOT_DIR/Include directory.
ISF_ROOT_DIR is the directory where ISF is installed. The header files are visible to
users because they may require access to the ISF interfaces and for rebuilding the
project.
IMPORTANT: Users are strongly discouraged from modifying these files.
• Header files associated with the project files for the user application are located in the
GetAccelData/Include directory for the project. These files can be modified as
needed for the user application.
1. Import project
2. Modify application
3. Build application
4. Connect hardware
5. Configure connection
6. Establishcommunication
7. Run application
8. TestModule 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
11
Add CI Component to the Project (continued)
As provided, the GetAccelData project does not include the Command Interpreter
component.
To work with the Command Interpreter component, it must be added to the project. To do
this, two header files must be modified.
• Modify isf_user_config.h to turn on the component
• Modify GetAccelData_main.c to add the CI function declarations to the user
application by including the isf_ci.h header file
Doing this allows full access to the functions of the Command Interpreter.
1. In CodeWarrior, open the isf_user_config.h file, located in the Include directory in
the CodeWarrior project (Include/isf_user_config.h).
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
12
Add CI component to the Project (continued)
2. Locate the ISF_COMPONENT_CI macro, and then change it from 0 to 1.
3. Save the file.
Before
After
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
13
Add CI component to the Project (continued)
4. Open the GetAccelData_main.c file, located in the Source directory in
the CodeWarrior project (Source/GetAccelData_main.c).
5. Locate the ISF framework includes, and then add the Command
Interpreter function declarations to the user application by including the
isf_ci.h file as shown.
6. Save the file.
Note: isf_ci.h is one of the header files associated with ISF and
should not be modified.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
14
Checkpoint
At this point, the Command Interpreter component has been added
to the project—you are now ready to link the user application by
including the components necessary for the example in this module.
In summary, to include any given component from the ISF library:
• Modify isf_user_config.h to turn on the specific component
• Add the specific component header file to the user application.
To exclude any given component, turn off the component in
isf_user_config.h by changing 1 to 0.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
15
Command Interpreter Paradigms
A host may use commands in two distinct paradigms implemented in the ISF
Command Interpreter. Requirements on the host side will influence which
paradigm to use.
In the rest of this module, you will learn about the theory and use of both
paradigms.
• Command/Response
• Quick-Read (QR)
Command/Response is used when a host wants specific tasks to execute in
a user application on demand.
Quick-Read (QR) is used when a host wants to read the sensor data on a
periodic interval without sending a command packet and waiting for a
response.
In the rest of this module, you will learn how to produce both types of
commands which you use depending on your needs.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
16
Registering a CI Callback
The device may have multiple user applications running on it. Hence, each
user application that wishes to use the CI must register with the CI. This
registration allows ISF to know which commands are associated with the
specific user application. As part of the registration, the user application
specific callback is inserted into the registry. This callback is called
automatically whenever the host sends a specific command to the user
application on the device.
Registering a callback is a three step process.
1. Declare the callback function.
2. Insert the callback function into the CI registry.
3. Define the callback function.
See Wikipedia for more information regarding callbacks if required.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
17
Registering a CI Callback (continued)
The first step to registering a CI callback is to declare the callback function.
The callback is declared using the following function signature (or format).
For the example in GetAccelData, the callback is named accelCallback.
Hence, the callback is declared as:
Note that the only thing changed from the signature is the name of the
callback.
For information on the parameters, refer to the ISF API Reference Manual,
(ISF1P195K_API_REFERENCE_RM).
ci_response_t callBackName(ci_host_cmd_packet_t *pHost_packet,
ci_app_resp_packet_t *pApp_packet);
ci_response_t accelCallback(ci_host_cmd_packet_t *pHost_packet,
ci_app_resp_packet_t *pApp_packet);
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
18
Registering a CI Callback (continued)
Now, declare the callback function.
1. In CodeWarrior, open Source/GetAccelData_main.c.
2. Locate the Function Prototypes section, then insert the callback as
shown.
Note: This function declaration can be located anywhere before the function
definition. However, it is good practice to place it in the Function Prototypes
section.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
19
Registering a CI Callback (continued)
The second step to registering a CI callback is to insert the callback function into the CI
registry. This is done by inserting the callback into the default ISF CI callback array.
To complete the callback registration, the callback function name must be added to the default ISF callback array called ci_callback. The CI uses the array index as the
Application ID of the registered user application. This allows ISF to simultaneously keep
track of multiple user applications.
In this case, the ISF_APP_CALLBACKS macro defines the first two elements of the array.
The callback for this example, accelCallback, is added as the third element of the
array. Therefore, the GetAccelData application has Application ID 0x02.
// Command Interpreter callbacks. The array index is the ApplicationID.
const ci_funcp_t ci_callback[] =
{
// ISF callbacks come first.
ISF_APP_CALLBACKS
accelCallback
};
Therefore, the GetAccelData application has Application ID 0x02.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
20
Registering a CI Callback (continued)
Now, insert the callback function into the CI registry.
Add the callback as shown.
Before
After
Note: The edit
window may
display
question mark
icons in the
margin. In this
case, they may
be ignored.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
21
Registering a CI Callback (continued)
The third step to registering a CI callback is to define the callback function for handling the
command.
Add the snippet below to the bottom of the Source/GetAccelData_main.c file, and then
save the file.
Note: The code snippet can go anywhere but it is recommended that it be at the bottom of
file.
Note: For now, the accelCallback function is empty to get the file to compile or build.
The complete definition of the function occurs later in this module.
/*
* @name CI callback for the GetAccelData application.
*
* @brief Implements the host command for the accelerometer in this callback. CI calls this
* callback automatically when the host sends a command for this application.
*/
ci_response_t accelCallback(ci_host_cmd_packet_t *pHost_packet,
ci_app_resp_packet_t *pApp_packet)
{
}
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
22
Registering a CI Callback (continued)
After:Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
23
Checkpoint
The steps to register a callback are complete.
Clean and build the project, using what you learned in Module 3—Building
an ISF application. When the build is complete, the console displays a build
complete message.
1. Import project
2. Modify application
3. Build application
4. Connect hardware
5. Configure connection
6. Establishcommunication
7. Run application
8. Test
NOTES:If compilation errors exist,
typographical errors are very
likely present. Double check
for typographical errors.
Copying and pasting text from
this training module may
introduce issues with dropped
spaces. Check to make sure
no errors were introduced.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
24
Adding a Command/Response Host Command
The Command/Response paradigm is a synchronous interface which means that a
specified order is expected when using the 32 mailboxes on the FXLC95000.
1. An initial command from the host is placed into the mailboxes.
2. The ISF firmware responds to the command by putting the response data into the same
32 mailboxes.
3. A special bit called the Command Complete, or COCO, bit in MB1 is used to indicate
that the data is ready to be collected from the mailboxes.
4. A second command from the host is required to read the data from the mailboxes.
In this section, the necessary modifications for adding a Command/Response host
command continue. For the C/R host command, the values needed to be written to the
mailboxes to trigger the callback function are determined.
The two actions required for adding a Command/Response host command are:
• Create a sensor data buffer available to the callback function
• Implement the logic required to handle the host command
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
25
Command/Response Command Format
When using the Command/Response paradigm, the host commands are sent from the host to the
FXLC95000.
Command/Response commands consist of four fields, each one byte in size. In the case of C/R, the
host issues commands by writing specific values to these bytes.
Once the command enters the FXLC95000, the four command fields are placed into the first four
mailboxes, MB0:3. These bytes are always reserved as such, even for Quick-Read commands.
• The ApplicationID field describes the identification number for the user application registered with the Command Interpreter. The number corresponds to the location in the ci_callback
array beginning with index 0.
• The CommandID field specifies various operations or commands the CI can perform. ISF has some predefined commands located in ci_commands_enum in isf_ci.h.
• The Offset field specifies the byte number into the user application data buffer.
• The Number of bytes field is the number of data bytes the host wants to access.
Command Structure (Command/Response)
Field Field 1 Field 2 Field 3 Field4
Field contents ApplicationID CommandID Offset Number of bytes
Mailbox assignment MB0 MB1 MB2 MB3
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
26
Command/Response Command Format (continued)
Example
This example will show the process used to define a Command/Response command.
The objective is to create a host command to request the following sensor data from the
user application:
• four bytes of sample count
• six bytes of X,Y, Z accelerometer data.
Field 1: ApplicationID
The ApplicationID field describes the identification number for the user application
registered with the Command Interpreter. The number corresponds to the index in the ci_callback array.
Earlier in this module, accelCallback was declared in the third position of the
ci_callback array (index = 2).
Therefore, the value of Field 1 is 0x02.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
27
Command/Response Command Format (continued)
Field 2: CommandID
There are several command types listed in the ISF Software Reference Manual.
In this example, we are interested in reading data from an application’s output
buffer. Referencing the list, the appropriate command type is CI_CMD_READ_APP_DATA = 3. This value (3) is used as the CommandID.
Therefore, the value of Field 2 is 0x03.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
28
Command/Response Command Format (continued)
Field 3: Offset
The Offset specifies the starting location of the data to be read from the user application
output data buffer.
ISF uses the predefined type AfeDataPkt_t to return the sample count and
accelerometer data. For more information, refer to the ISF API Reference Manual
(ISF1P195K_API_REFERENCE_RM) .
• The first four bytes contain the tickCount.
• The next six bytes contain the X, Y and Z accelerometer data
Since the data is read from the beginning of the data buffer in this example, the offset is 0.
Therefore, the value of Field 3 is 0x00.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
29
Command/Response Command Format (continued)
Field 4: Number of bytes
The Number of bytes field is the number of data bytes the host wants.
In this example, the host wants 10 bytes.
• 4 bytes sample count
• 2 bytes X accelerometer data
• 2 bytes Y accelerometer data
• 2 bytes Z accelerometer data
Therefore, the value of Field 4 is 0x0A.
Together, based on the values determined for the four fields, the
Command/Response command is: 02 03 00 0A
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
30
Adding a Host Command
A data buffer needs to be defined to hold the sensor data available to the callback function, accelCallback, in response the read command from the host. In our example, the action is
completed by making the local variable into a global variable. In the user_task function, make
the local variable
AfeDataPkt_t accelSampleData; /* The buffer which receives the accelerometer data. */
available to accelCallback by moving it to the global variables section. As a result, the variable
accelSampleData can be accessed in the accelCallback callback function.
Comment
out local
variable
here (or
delete)
Insert global variable here
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
31
Adding a Host Command (continued)
Next, implement logic to handle the host command in the callback function, which is called
automatically whenever a specific command is received by the device.
The general logic is:
Identify the type of command
Validate the command
Send and receive data to and from the host
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
32
Adding a Host Command (continued)
Now, implement the logic to handle the host command in the callback function, accelCallback .
1. Locate the empty callback function defined earlier in this module.ci_response_t accelCallback(ci_host_cmd_packet_t *pHost_packet, ci_app_resp_packet_t *pApp_packet)
2. Insert the following code snippet into the empty accelCallback callback function.
ci_response_enum callbackRet = CI_ERROR_NONE;
switch(pHost_packet->cmd)
{
/* This is the command type for requesting user application data.*/
case CI_CMD_READ_APP_DATA:
// Validate the requested data size
if(pHost_packet->byte_cnt > sizeof(AfeDataPkt_t)){
callbackRet = CI_INVALID_COUNT;
break;
}
// Validate the requested data size from the offset.
if(pHost_packet->offset + pHost_packet->byte_cnt > sizeof(AfeDataPkt_t) ){
callbackRet = CI_ERROR_COMMAND;
break;
}
// Send the accelerometer data to the host.
pApp_packet->bytes_xfer = (uint8)isf_ci_app_write(pHost_packet->appId,
(uint32)pHost_packet->byte_cnt,
(uint8*)((uint8*)&accelSampleData + pHost_packet->offset));
break;
default:
callbackRet = CI_ERROR_COMMAND;
break;
}
return callbackRet;
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
33
Adding a Host Command (continued)
Identify the command type from the Host command
Validate the command
Send back the accelerometer data to the host using the CI write function, isf_ci_app_write
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
34
Adding a Host Command (continued)
The process is the same when implementing other CI commands, such as:
CI_CMD_READ_CONFIG
allows the host to read the configuration data supplied by the application
CI_CMD_WRITE_CONFIG
allows the host to write specific configuration data to the application
The implementation logic is just like what was done on the previous slides by applying the
same steps.
Identify the type of command
Validate the command
Send and receive data to and from the host
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
35
Adding a Host Command (continued)
In this module, since an existing user application is being modified, some clean-up is required
to give full control to the Command Interpreter for mailbox management and avoid overlapping
data in mailboxes.
Delete the following code snippet for direct mailbox access from the function user_task in
the Source/GetAccelData_main.c source code. (Located approximately at line 220.)
This completes the necessary modifications for adding a Command/Response host command.
/*
* Put the data and stats in the mailboxes to be ready by the host.
*/
/* SP_MB1_dword is a 4-byte word at SP_MB4-SP_MB7. */
SP_MB1_dword = sampleCount;
/* SP_MB2_dword is a 4-byte word at SP_MB8-SP_MB11. */
SP_MB2_dword = missedSamples;
/* SP_MB6_word is a 2-byte word at SP_MB12-SPMB13. */
SP_MB6_word = accelSampleData.afeData.accel[0];
/* SP_MB7_word is a 2-byte word at SP_MB14-SPMB15. */
SP_MB7_word = accelSampleData.afeData.accel[1];
/* SP_MB8_word is a 2-byte word at SP_MB16-SPMB17. */
SP_MB8_word = accelSampleData.afeData.accel[2];
/* Let the host the mailboxes are updated with valid data. */
SP_MB1 = 0x80;
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
36
Building the Image
The necessary source code modifications for adding a host command are
complete.
Clean and build the project, using what you learned in Module 3—Building
an ISF application. When the build is complete, the console displays a build
complete message.
1. Import project
2. Modify application
3. Build application
4. Connect hardware
5. Configure connection
6. Establishcommunication
7. Run application
8. Test
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
37
Connecting the Hardware,
Configuring the Connection,
Establishing Communication
Steps 4, 5, and 6, for this module are similar to the corresponding steps
completed in earlier modules.
For the purposes of this training, the method of using the Mailbox Tool to load
the S19 file is being used.
1. Import project
2. Modify application
3. Build application
4. Connect hardware
5. Configure connection
6. Establishcommunication
7. Run application
8. Test
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
38
Establishing Communication
1. Locate and open the Intelligent Sensor Mailbox Tool
(ISF1P1WIN_MAILBOX_TOOL_EXE.exe)
2. Click Open Comm.
Verify that communication is established. (If communication is not established, reset the
board and try again.)
• Running ROM code is displayed in the console
• Connected to Device is indicated in the status bar
You are now ready to transfer the S19 Binary image to the FXLC95000CL device and run
the application.
• Return to the mailbox tool and switch over to the “Flash Utility” tab .
• In case there is another image already in flash, begin by pressing “Erase Flash”.
• Now select “Program Flash” and select the S19 file from the CodeWarrior workspace
C:\Users\...\workspace_module5\GetAccelData\Build\Binary\GetAccelData.elf.S19
• Select “Boot to Flash”.
1. Import project
2. Modify application
3. Build application
4. Connect hardware
5. Configure connection
6. Establishcommunication
7. Run application
8. Test
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
39
Command/Response Checkpoint
With communication established, the new build completed, and the application running
on the Application Board, you can send the command defined in this exercise using
the Intelligent Sensor Mailbox Tool.
1. In the Intelligent Sensor Mailbox Tool, on the “Mail Box” tab,
enter 02 03 00 0A in the Bytes to Write field, and then click MB Write.
This sends the command to the user application causing the registered callback
to put sensor data into the mailboxes.
This is the first stage in the command/response synchronization.
1. Import project
2. Modify application
3. Build application
4. Connect hardware
5. Configure connection
6. Establishcommunication
7. Run application
8. TestModule 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
40
Command/Response Checkpoint (continued)
2. Read the mailbox data by clicking MB Read button. This is the second command
described in the command/response synchronization.
The sample user application provides the sample count and X, Y, Z accelerometer data.
• MB0:3 contain the status response
— Note that MB1 has changed from 03 on input to 80 on output. This is because
of the COCO bit which is set (making bit 7 = 1) on command completion.
— In addition, MB2 has changed from 00 to 0A. On output, MB2 tells how many
bytes were actually transferred. Since it matches the value in MB3, you know
the transaction was successful.
• MB4:7 contain the sample count
• MB8:13 contain the X, Y, Z accelerometer data
MB8:13MB0:3 MB31MB4:7
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
41
Command/Response Checkpoint (continued)
To obtain the next set of data, you may send the same command by
clicking MB Write and then MB Read.
You have implemented a host command and seen that the
Command/Response paradigm supported by ISF Command
Interpreter is a synchronous interface requiring a host command.
Next, you will implement the data management for a host application
using the Quick-Read paradigm.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
42
Implementing Quick-Read Support
How can a user application make sensor data available to the host without
sending a command and waiting for a response?
Can the data be made available to certain mailboxes configured by the host?
The CI enables this type of data management through the Quick-Read (QR)
paradigm which provides asynchronous communication between a user
application and the host where the user application updates the data into
special QR mailboxes configured by the host. This allows the host to obtain
data as needed without any firmware intervention. The mapping of data from
the user application to the QR mailboxes specified by the host is managed by
the CI without any need for synchronous intervention.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
43
Implementing Quick-Read Support (continued)
The first step is to configure the mailboxes for Quick-Read.
The CI has a special command structure and a specific mailbox application
used to configure QR. The mailbox application has a set of configuration
registers or input buffers. These registers assign two attributes to each
mailbox, called a QR pair.
(i) an application ID which matches the user application to its QR data
and
(ii) A byte offset which specifies the offset into the user application’s output
data buffer.
Note that the appID for this special mailbox application that performs QR configuration
is 0x01.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
44
Implementing Quick-Read Support (continued)
The diagram shows the QR command structure starting from mailbox zero (MB0).
Each field is one byte in length.
As before, when the command comes from the host into the FXLC95000, the command
goes into the 32 mailboxes. This means that command width must be less than or equal to
32. The discussion going forward assumes that the command is already located in the
mailboxes on the FXLC95000.
1
Note that the appID for this special mailbox application that performs QR configuration
is 0x01.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
45
Implementing Quick-Read Support (continued)
Note that the first four bytes of the command corresponding to MB0:3 are dedicated for
command/ response transfers and cannot be configured for Quick-Read.
Mailboxes MB4:31 can be configured by the host for Quick-Read. Any or all of these
mailboxes can be configured for Quick-Read. The command can extend to MB31 but it
does not have to do so. However, it is assumed that the command definition continues as
long as there are QR pairs. As soon as the QR pairs end, then the command ends with the
last QR pair. There is an example later in this module.
The commands are sent from the host to the FXLC95000.
The Quick Read mailboxes are output from the FXLC95000 to the host.
The mailboxes are the communication mechanism in both cases.
The commands have to communicate to the FXLC95000 which mailboxes the host is
expecting to read for Quick Read data.
If a mailbox pair is configured by the host for Quick-Read data, it cannot be used by the CI
for Command/Response data transfer, and the host should not write to these mailboxes.
QR mailboxes are written by the user application and read by the host.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
46
Implementing Quick-Read Support (continued)
MB0: The Application ID field contains the
identification number of the special Command
Interpreter mailbox application registered with
the Command Interpreter (CI). This is always
0x01 for Quick-Read.
MB1: The Command ID field is the type of
command the CI can handle for the mailbox
application. (For the types of commands
possible in the CI, see page 30 of the
ISF1P195K_SW_REFERENCE_RM.)
MB2: The Offset field is the offset into the
mailbox application data buffer or register.
MB3: The Number of Bytes field is the length of
the data bytes in the command.
SP_MB0 SP_MB1 SP_MB2 SP_MB3
Application ID
Command ID OffsetNumber of Bytes
Mailbox Application
Mailbox Application
Mailbox Application
Mailbox Application
Dedicated for command/response
1
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
47
Implementing Quick-Read Support (continued)
The User App ID is the ID of the user application that provides the QR data.
The Offset of the User App is the offset into the user application’s data buffer.
Refer to the ISF1P195K_SW_REFERENCE_RM for more details.
SP_MB4 SP_MB5 SP_MB6 SP_MB7
…
SP_MB30 SP_MB31
User App IDOffset
(User App)User App ID Offset
(User App)User App ID Offset
(User App)
Mailboxes that may be configured for Quick-Read access.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
48
Implementing Quick-Read Support (continued)
This illustrates how different user applications can choose to map
different mailboxes to different outputs for Quick Read.
App3Inputs
0
1
2
…
n
Application ID 3
App3Outputs
0
1
2
…
n
App4Inputs
0
1
2
…
n
Application ID 4
App4Outputs
0
1
2
…
n
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
49
Implementing Quick-Read Support (continued)
The following table, from the ISF Software Reference Manual, shows the
mapping between the mailbox application input buffer offset and the physical
mailboxes on the FXLC95000.
Note that CI Input Buffer Byte
Offset 0 and 1 are associated
with QR and the physical
mailbox, MB4. The value in
this input buffer configures the
QR data of the user application
in the physical mailbox MB04.
This will be used on the next
slide.
CI Input Buffer
Byte Offset QR Mailbox
Table A – Mailbox App Inputs
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
50
CI Input
Buffer
byte offset
Buffer
Name
(Parameter)
5
The mailbox application maps its buffers directly to the physical mailboxes for the QR data.
The command input below is interpreted by the mailbox application as a user application
with App ID 2 placing its 6th byte of output data in the physical QR MB4.
• In the command, the offset of 0 (red circle) matches the CI Input Buffer Byte Offset 0 in Table
A corresponding to QR MB4.
• In the command, the User App ID is 2 (blue square).
• In the command, the offset into App2’s output data buffer is 5 (red triangle), which is the sixth
byte.
1
Implementing Quick-Read Support (continued)
App2Inputs
0
1
2
…
n
Application ID 2
App2Outputs
a
b
c
d
e
f
Command Input
Command Output
2Table A – Mailbox App Inputs
5
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
51
Implementing Quick-Read Support (continued)
Let’s check your understanding.
Suppose you want to put the 3rd byte of output data from user application
ID=7 into MB9.
What are the entries in Table A for the CI Input Buffer byte offset and the
corresponding parameter?
App7Inputs
0
1
2
…
n
Application ID 7
App7Outputs
a
b
c
…
n
Table A – Mailbox App Inputs
Hint: You will need to go
back to the complete
Table A on slide 49.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
52
Implementing Quick-Read Support (continued)
Suppose you want to put the 3rd byte of output data from user application ID=7 into MB9.
What are the entries in the CI Input Buffer byte offset and the corresponding parameter?
App7Inputs
0
1
2
…
n
Application ID 7
App7Outputs
a
b
c
…
n
Now that you have confirmed your understanding of the output, what
would the input command for this specific example look like?
Table A – Mailbox App Inputs
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
53
Implementing Quick-Read Support (continued)
Now that you have confirmed your understanding of the output, what would the
input command for this specific example look like?
App7Inputs
0
1
2
…
n
Application ID 7
App7Outputs
a
b
c
…
n
Command Input:
Table A – Mailbox App Inputs
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
54
Implementing Quick-Read Support (continued)
Now, consider a more true to life example.
What is the command to configure ISF to write the 6 bytes of accelerometer data (x, y, z) into
mailboxes 18 through 23 (MB18:23) as QR. What would the configuration command be?
Remember that the first four bytes are reserved for command/response.
Then, since we want 6 bytes of accelerometer data, we need six pairs or twelve bytes in the
command to lay out the location of the data.
This means that our command is 16 bytes long.
Construct the command byte by byte starting with byte 0.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
55
Implementing Quick-Read Support (continued)
What is the command to configure ISF to write the 6 bytes of accelerometer data (x, y, z) into
mailboxes 18 through 23 (MB18:23) as QR. What would the configuration command be?
Beginning with byte 0, what is the application ID of the command that configures the QR?
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
56
Implementing Quick-Read Support (continued)
What is the command to configure ISF to write the 6 bytes of accelerometer data (x, y, z) into
mailboxes 18 through 23 (MB18:23) as QR. What would the configuration command be?
Beginning with byte 0, what is the application ID of the command that configures the QR?
The first byte is the application ID of the mailbox application is always 1.
The second byte is determined by the type of command used in the QR. There are several
types of commands listed in the ISF Software Reference Manual. This can also be determined by looking at ci_commands_enum in the header file isf_ci.h.
1
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
57
Implementing Quick-Read Support (continued)
What is the command to configure ISF to write the 6 bytes of accelerometer data (x, y, z) into
mailboxes 18 through 23 (MB18:23) as QR. What would the configuration command be?
The second byte is determined by the type of command used in the QR. There are several
types of commands listed in the ISF Software Reference Manual. This can also be determined by looking at ci_commands_enum in the header file isf_ci.h.
The CI_CMD_WRITE_CONFIG = 2.
1 2
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
58
Implementing Quick-Read Support (continued)
What is the command to configure ISF to write the 6 bytes of accelerometer data (x, y, z) into
mailboxes 18 through 23 (MB18:23) as QR. What would the configuration command be?
The third byte is determined by the offset into the
Command Interpreter Input Buffer Byte Offset. Use
the table on the right (from the ISF Software
Reference Manual).
1 2
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
59
Implementing Quick-Read Support (continued)
What is the command to configure ISF to write the 6 bytes of accelerometer data (x, y, z) into
mailboxes 18 through 23 (MB18:23) as QR. What would the configuration command be?
The third byte is determined by the offset into the
Command Interpreter Input Buffer Byte Offset. Use
the table on the right (from the ISF Software
Reference Manual).
Mailbox 18 corresponds to an offset value of 28.
28 written in hexadecimal is 1C which becomes the
third value in the QR Configuration Command.
The fourth byte contains the number of bytes of data
involved. What is the correct value?
1 2 1C
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
60
Implementing Quick-Read Support (continued)
What is the command to configure ISF to write the 6 bytes of accelerometer data (x, y, z) into
mailboxes 18 through 23 (MB18:23) as QR. What would the configuration command be?
The fourth byte contains the number of bytes of data involved. What is the correct value?
We have 6 bytes of QR data to be configured. Each byte of QR data requires two
configuration bytes—one for the Application ID and one for the offset.
Multiplying 6 by 2 gives a total of 12, which is C in hexadecimal .
This completes the command values.
Beginning with the fifth byte, the focus moves to the data values which are provided in pairs. In
this case, the interest is in the first byte of the x value of the accelerometer which is two bytes
long.
1 2 1C C
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
61
Implementing Quick-Read Support (continued)
What is the command to configure ISF to write the 6 bytes of accelerometer data (x, y, z) into
mailboxes 18 through 23 (MB18:23) as QR. What would the configuration command be?
Beginning with the fifth byte, the focus moves to the data values which are provided in pairs. In
this case, the interest is in the x value of the accelerometer which is two bytes long.
Bytes 6 and 7 are easy because they contain the second byte of the x value of the
accelerometer. What would the values be for the next two bytes of the command?
1 2 1C C 2 4
The output format of the accelerometer provided in
the core library for this application ID is:
• Bytes 0-3 contain the ticket count
• Bytes 4-9 contain the accelerometer x, y, z
values from the accelerometer
It is out of the scope of this training to show you
where this is defined in the code. For now, accept
this as a definition.
Recall from slide 19 that the User
Application ID for GetAccelData is 2.
This becomes the value for byte 5.
Byte 6 contains the index of the output
buffer that contains the first byte of the x
value of the accelerometer. It turns out
that this value is the fifth byte of the
output buffer for app2 or getAccelData.
The offset is 4.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
62
Implementing Quick-Read Support (continued)
What is the command to configure ISF to write the 6 bytes of accelerometer data (x, y, z) into
mailboxes 18 through 23 (MB18:23) as QR. What would the configuration command be?
Byte 6 and 7 are easy because they contain the second byte of the x value of the
accelerometer. What would the values be for the next two bytes of the command?
The User App ID for GetAccelData is still 2. The second byte of data is in output buffer
location 5 (refer back to slide 61).
Now, we are looking for the y value of the accelerometer. It is also from GetAccelData and is
also two bytes long. You should be able to identify the values for the next four bytes of the
command this time.
1 2 1C C 2 4 2 5
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
63
Implementing Quick-Read Support (continued)
What is the command to configure ISF to write the 6 bytes of accelerometer data (x, y, z) into
mailboxes 18 through 23 (MB18:23) as QR. What would the configuration command be?
Now, we are looking for the y value of the accelerometer. It is also from GetAccelData and is
also two bytes long. You should be able to identify the values for the next four bytes of the
command this time.
User App ID for GetAccelData remains 2. The first byte of the y value is in output buffer byte 6,
while the second byte is in output buffer byte 7 (refer back to slide 61).
The last four bytes contain the mapping for the z value of the accelerometer.
1 2 1C C 2 4 2 5 2 6 2 7
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
64
Implementing Quick-Read Support (continued)
What is the command to configure ISF to write the 6 bytes of accelerometer data (x, y, z) into
mailboxes 18 through 23 (MB18:23) as QR. What would the configuration command be?
The last four bytes contain the mapping for the z value of the accelerometer.
The App ID for GetAccelData remains 2. The first byte of the z value is in output buffer byte 8
while the second byte is in output bugger byte 9 (refer back to slide 61).
This shows how the mailboxes are set up when the command comes into the CI.
Based upon this command, sketch out the mailbox configuration for the data being returned to
the host.
1 2 1C C 2 4 2 5 2 6 2 7 2 8 2 9
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
65
Implementing Quick-Read Support (continued)
QR Configuration Command
This shows how the mailboxes are set up when the command comes into the CI.
Based upon this command, sketch out the mailbox configuration for the data being returned
to the host.
Note that once certain mailboxes are configured for QR, the host should track how many
mailboxes remain contiguous for general command/response type data. Refer to the
ISF1P195K_SW_REFERENCE_RM for more details. In this case, MB4:17 are contiguous
and available for C/R or QR. MB24:31, while contiguous are only available for QR
configuration. A new QR configuration command would be required in either case.
1 2 1C C 2 4 2 5 2 6 2 7 2 8 2 9
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
66
Implementing Quick-Read Support (continued)
Now that you understand the commands, it is time to implement the logic in the user application to update the QR mailboxes whenever the data is available. The isf_ci_qr_update function is
defined as part of the CI (refer to the API Reference Manual ISF1P195K_API_REFERENCE_RM).
Insert the following code snippet into GetAccelData after the sensor data is retrieved from the Sensor Manager using isf_sm_get_sensor_data. Navigate to the user_task function in
Source\GetAccelData_main.c and add:
isf_ci_qr_update(0x2, (int8)sizeof(accelSampleData), (uint8 *)&accelSampleData);
isf_ci_qr_update parameters are:
• The appID of GetAccel Data
• The size of the data buffer
• The address of the data buffer
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
67
Quick-Read Checkpoint
You have completed the necessary modification for Quick-Read
support.
1. Clean and build the project.
2. Flash the updated image onto the application board as before.
(It is recommended to close and reopen the Mailbox Tool.)
3. With the application running on the Application Board, you can
send a command using the Intelligent Sensor Mailbox Tool.
Using the Intelligent Sensor Mailbox Tool, enter the following
command in the Bytes to Write field to configure the QR
mailboxes.
01 02 1C 0C 02 04 02 05 02 06 02 07 02 08 02 09
4. Click MB Write. This sends the command to the mailbox
application, configuring MB18:23 as Quick-Read.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
68
Quick-Read Checkpoint (continued)
4. Read the mailboxes by clicking MB Read.
Note that the accelerometer data is placed in MB18:23.
MB18:23MB0
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
69
In theory, there could be up to 14 different user applications getting one set of QR data or
one user application getting 14 sets of QR data in a single command.
Suppose you wanted to configure more than 14 mailboxes for Quick-Read, say 16.
Clearly, it would require 2 commands.
Even though one of the earlier examples “configured” MB4, it doesn’t makes sense to start
there because it is needed for the second of the two commands and would be overwritten.
Also, it may be needed for future C/R commands. For this reason, it is a better idea to
configure the higher number mailboxes first.
For this exercise, let’s configure MB16:MB31 for Quick-Read.
There are many ways to split this up. Following the recommendation, the first command
configures MB18-31 and the second command configures MB16-17.
Quick-Read Exercise
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
70
For this exercise, let’s configure MB16:MB31 for Quick-Read, the last 16 bytes of the
mailboxes.
The first command first.
It is a QR configuration command so the first byte has a value of 1. For the purposes of
this discussion, CI_CMD_WRITE_CONFIG is still being used which has an Command ID
of 2. Since we are starting the configuration at MB18, what is the value for MB2 in the
command? MB3 value?
Advanced Quick-Read Exercise
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
71
For this exercise, let’s configure MB16:MB31 for Quick-Read, the last 16 bytes of the
mailboxes. First of two QR configuration commands.
Quick-Read Exercise
For the first command, MB:18-31 are configured.
For the second command, MB:16-17 are configured.
MB2 value: The offset is 28. The hexadecimal value
for 28?
MB3 value: 14 mailboxes times 2 = 28.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
72
For this exercise, let’s configure MB16:MB31 for Quick-Read, the last 16 bytes of the
mailboxes. First of two QR configuration commands.
Quick-Read Exercise
The rest of the entries would have the appID of the user application providing the data. For
our purposes, it doesn’t matter, let’s say 8.
The data values from the output buffer are also not important for this discussion. Let’s say
the output buffer data corresponds to the desired mailbox configuration, i.e. output data buffer
value 0 goes into MB:16, output data buffer value 1 goes into MB:17, …, and output data
buffer value 15 goes into MB:31.
What does the rest of the first command look like?
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
73
For this exercise, let’s configure MB16:MB31 for Quick-Read, the last 16 bytes of the
mailboxes. First of two QR configuration commands.
Quick-Read Exercise
Now we have to create the second command to configure MB:16 and MB:17 for
QuickRead.
The first two bytes are the same as the first command, it is still QR Configuration and still
CI_CMD_WRITE_CONFIG.
Will the offset and number of bytes be the same as well? Try to determine what the third
and fourth bytes of the command before going to the next slide.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
74
For this exercise, let’s configure MB16:MB31 for Quick-Read, the last 16 bytes of the
mailboxes. Second of two QR configuration commands.
Quick-Read Exercise
The offset for MB16 is 24 which has a hexadecimal
value of 18.
We have 2 MBs to configure. 2 times 2 is 4.
“QR” has been left in the mailbox model to remind us
not to have commands overwrite these mailboxes
going forward.
What are the last four bytes of the command?
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
75
For this exercise, let’s configure MB16:MB31 for Quick-Read, the last 16 bytes of the
mailboxes. Second of two QR configuration commands.
Quick-Read Exercise
You can carry the thought exercise further by determining how many commands are
required to configure the maximum number of mailboxes for QR.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
76
Module Summary
This completes Module 5—Using the Command Interpreter.
At this point, you know how to:
• Add and remove components of ISF into the project.
• Implement a host command using the Command/Response paradigm
available in the Command Interpreter.
• Use ISF header files and the contents of the header files to develop User
Applications which can communicate with the host.
• Configure the mailboxes for Quick-Read by the host allowing the host to
access sensor data on a periodic basis.
Whenever modifying any user application, we recommend that you make
incremental changes and check your work as each change is made.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM
77
Next Steps
Now that you know the basics of communications between
the host and the embedded application for gaining access to
sensor data, the next major thing to learn would be to add
an external sensor using one of the sensor adapters
provided by FSL.
In Module 6, you will learn how to add an external sensor.
Module 5
ObjectivesPrerequisitesRequired Items
OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read
Module SummaryNext Steps
TM