SensorStudio User Documentation - TDK
47
SensorStudio User Documentation InvenSense reserves the right to change the detail specifications as may be required to permit improvements in the design of its products. InvenSense Inc. 1745 Technology Drive, San Jose, CA 95110 U.S.A +1(408) 988–7339 www.invensense.com Document Number: AN-000078 Revision: 1.0 Date: 10/28/2015 SensorStudio User Documentation
Transcript of SensorStudio User Documentation - TDK
SensorStudio User Documentation
InvenSense reserves the right to change the detail specifications as may be required to permit improvements
in the design of its products.
InvenSense Inc. 1745 Technology Drive, San Jose, CA 95110 U.S.A
+1(408) 988–7339 www.invensense.com
Document Number: AN-000078 Revision: 1.0 Date: 10/28/2015
SensorStudio User Documentation
SensorStudio User Documentation
Document Number: AN-000078 Page 2 of 47 Revision: 1.0 Date: 10/28/2015
TABLE OF CONTENTS table of figures (If Applicable) .................................................................................................................................................................... 3
Table of Tables (If Applicable) .................................................................................................................................................................... 5
1 Document Information ...................................................................................................................................................................... 6
1.1. Purpose of the Document ............................................................................................................................................................. 6
1.2. References .................................................................................................................................................................................... 6
1.3. Terminology .................................................................................................................................................................................. 6
2 Scope .................................................................................................................................................................................................. 8
2.1 overview ....................................................................................................................................................................................... 8
3 Quick start guide ................................................................................................................................................................................ 9
3.1 Overview ....................................................................................................................................................................................... 9
3.2 Installing SensorStudio ............................................................................................................................................................... 10
3.3 Connecting FireFly ...................................................................................................................................................................... 16
3.4 Evaluating FireFly ........................................................................................................................................................................ 17
3.5 Create a Flow .............................................................................................................................................................................. 21
3.6 Design your sensor Algorithm ..................................................................................................................................................... 25
3.7 Sensor Framework explained ..................................................................................................................................................... 31
3.8 Design your Sensor Driver .......................................................................................................................................................... 33
4 SensorStudio Reference Manual ...................................................................................................................................................... 37
4.1 Main screen ................................................................................................................................................................................ 37
4.2 FireFly.......................................................................................................................................................................................... 38
4.3 Flow area .................................................................................................................................................................................... 40
4.4 Help window ............................................................................................................................................................................... 40
4.5 Properties window ...................................................................................................................................................................... 41
4.6 Pool window ............................................................................................................................................................................... 42
4.7 Flow window ............................................................................................................................................................................... 43
4.8 LUA script .................................................................................................................................................................................... 44
3. Revision History ............................................................................................................................................................................... 46
SensorStudio User Documentation
Document Number: AN-000078 Page 3 of 47 Revision: 1.0 Date: 10/28/2015
TABLE OF FIGURES (IF APPLICABLE) Figure 1. Screenshot of InvenSense SensorStudio Setup Wizard ....................................................................................... 10
Figure 2. Screenshot of InvenSense SensorStudio Setup Wizard EULA ............................................................................. 10
Figure 3. Screenshot of InvenSense SensorStudio Setup Wizard install path ..................................................................... 11
Figure 4. Screenshot of InvenSense SensorStudio Setup Wizard start menu ..................................................................... 11
Figure 5. Screenshot of InvenSense SensorStudio Setup Wizard desktop shortcut............................................................ 12
Figure 6. Screenshot of InvenSense SensorStudio Setup Wizard install ............................................................................. 12
Figure 7. Screenshot of InvenSense SensorStudio Setup Wizard installing ........................................................................ 13
Figure 8. Screenshot of InvenSense SensorStudio Setup Wizard Arduino driver ................................................................ 13
Figure 9. Screenshot of Microsoft Visual Redistributable ..................................................................................................... 14
Figure 10. Screenshot of Microsoft Visual Redistributable complete ................................................................................... 15
Figure 11. Screenshot of InvenSense SensorStudio Setup Wizard complete ..................................................................... 15
Figure 12. Picture of ICM30630 DK and J-Link probe .......................................................................................................... 16
Figure 13. Screenshot of Welcome Screen, Get Started tab ................................................................................................ 17
Figure 14. Screenshot of FireFly Orientation sample ........................................................................................................... 17
Figure 15. Screenshot of FireFly Start/Stop Push Button ..................................................................................................... 18
Figure 16. Screenshot of ICM30630 Properties Window ...................................................................................................... 19
Figure 17. Screenshot of ICM-30630 Help Window.............................................................................................................. 19
Figure 18. Screenshot of ICM-30630 properties (AvailableSensors) ................................................................................... 20
Figure 19. Screenshot of Help menu/Welcome Item ............................................................................................................ 20
Figure 20. Screenshot of Search for ICM device block in Pool Window............................................................................... 21
Figure 21. Screenshot of ICM30630 added to Flow area ..................................................................................................... 21
Figure 22. Screenshot of Flow with Accelerometer, Gyroscope & GameRotationVector blocks ......................................... 21
Figure 23. Screenshot of Flow connections between ICM30630 device and its Sensor Framework features..................... 22
Figure 24. Screenshot of Sliding Panel in Pool Window ....................................................................................................... 22
Figure 25. Screenshot of Flow with Sliding for Accelerometer & Gyroscope ....................................................................... 22
Figure 26. Screenshot of Flow window ................................................................................................................................. 23
Figure 27. Screenshot of Connected ICM30630................................................................................................................... 23
Figure 28. Screenshot of Running FireFlySensor Framework and SensorStudio Flow ....................................................... 23
Figure 29. Screenshot of GRVector block & Cube Panel to Visualize FireFly Device Orientation in Space........................ 24
Figure 30. Screenshot of File Menu Save As… .................................................................................................................... 24
Figure 31. Screenshot of Add CustomSensorDesigner to create your algorithm in C code ................................................ 25
Figure 32. Screenshot of CustomSensorDesign Properties ................................................................................................. 25
Figure 33. Screenshot of CustomSensorDesign C Editor .................................................................................................... 25
Figure 34. Picture of ICM30630 Arduino horizontal rotation ................................................................................................. 26
Figure 35. Screenshot of Original Skeleton Code Versus DoorOpeningDetection Code for init() ....................................... 26
Figure 36. Screenshot of Original Skeleton Code versus DoorOpeningDetection code for data_event()............................ 26
Figure 37. Screenshot of CustomSensorDesign Properties Format..................................................................................... 27
SensorStudio User Documentation
Document Number: AN-000078 Page 4 of 47 Revision: 1.0 Date: 10/28/2015
Figure 38. Screenshot of CustomSensor Properties Format selection................................................................................. 27
Figure 39. Screenshot of CustomSensor Properties Format help ........................................................................................ 27
Figure 40. Screenshot of FireFly toolbar Build button .......................................................................................................... 28
Figure 41. Screenshot of “Build and flash” configuration ...................................................................................................... 28
Figure 42. Screenshot of “Build and flash” window successful build .................................................................................... 28
Figure 43. Screenshot of FireFly “Flash” window ................................................................................................................. 29
Figure 44. Screenshot of ICM30630 Firmware Image Path ................................................................................................. 29
Figure 45. Screenshot of Door Opening Detection sample .................................................................................................. 30
Figure 46. Screenshot of Image Panel ................................................................................................................................. 30
Figure 47. Sensor Framework overall operation diagram ..................................................................................................... 31
Figure 48. Screenshot of AuxiliarySensorDesigner in Pool window ..................................................................................... 33
Figure 49. Screenshot of AuxiliarySensorDesigner flow ....................................................................................................... 33
Figure 50. Screenshot of AuxiliarySensorDesigner Properties ............................................................................................. 33
Figure 51. Screenshot of AuxiliarySensorDesigner Code Sample ....................................................................................... 34
Figure 52. Screenshot of AuxiliarySensorDesigner code sample I2C read/write ................................................................. 34
Figure 53. Screenshot of AuxiliarySensorDesigner code sample MyCustomTaskCode() ................................................... 35
Figure 54. Screenshot of AuxiliarySensorDesigner Code Sample init() ............................................................................... 35
Figure 55. Screenshot of AuxiliarySensorDesigner Code Sample subscribe_event() ......................................................... 36
Figure 56. Screenshot of AuxiliarySensorDesigner Code Sample period_event() ............................................................... 36
Figure 57. Screenshot of InvenSense SensorStudio with orientation project file opened .................................................... 37
Figure 58. Screenshot of “Build and flash” configuration ...................................................................................................... 38
Figure 59. Screenshot of “Build and flash” window successful build .................................................................................... 38
Figure 60. Screenshot of FireFly “Flash” window ................................................................................................................. 39
Figure 61. Screenshot of FireFly menu ................................................................................................................................. 39
Figure 62. Screenshot of InvenSense SensorStudio View Menu ......................................................................................... 40
Figure 63. Screenshot of ICM-30630 Help Window.............................................................................................................. 40
Figure 64. Screenshot of CustomSensorDesign Properties Format help ............................................................................. 41
Figure 65. Screenshot of ICM30630 Properties window ...................................................................................................... 41
Figure 66. Screenshot of Pool Window ................................................................................................................................. 42
Figure 67. Screenshot of AuxiliarySensorDesigner in Pool window ..................................................................................... 42
Figure 68. Screenshot of Flow window ................................................................................................................................. 43
Figure 69. Screenshot of Flow menu .................................................................................................................................... 43
Figure 70. Screenshot of ButtonInput Properties .................................................................................................................. 44
Figure 71. Screenshot of Lua Editor ..................................................................................................................................... 44
Figure 72. Screenshot of Lua Script Default Code Sample .................................................................................................. 45
SensorStudio User Documentation
Document Number: AN-000078 Page 5 of 47 Revision: 1.0 Date: 10/28/2015
TABLE OF TABLES (IF APPLICABLE) Table 1 .................................................................................................................................................................................... 6
ADDITIONAL USEFUL LINKS INVENSENSE WEBSITE: http://www.InvenSense.com/ ARDUINO WEBSITE: https://www.arduino.cc/en/Guide/Environment https://www.arduino.cc/en/Main/ArduinoBoardZero https://www.arduino.cc/en/uploads/Main/Arduino-Zero-schematic.pdf
ADDITIONAL DOCUMENTS ICM-30630 Datasheet ICM-30630 System Hardware Design Guide ICM-30630 Application Note: Using Eclipse IDE with J-Link Debugger ICM-30630 eMD Software User Guide ICM-30630 Command Protocol and Architecture ICM-30630 Shield Hardware Guide
SensorStudio User Documentation
Document Number: AN-000078 Page 6 of 47 Revision: 1.0 Date: 10/28/2015
1 DOCUMENT INFORMATION
1.1. PURPOSE OF THE DOCUMENT The purpose of the document is to get you started with the important concepts needed to work with InvenSense SensorStudio. The document consists of a Quick Start Guide (see 3) and a Reference Manual (see 4) sections.
1.2. REFERENCES ID NAME LINK
[1] ICM-30630 Datasheet http://www.invensense.com/products/icm-30630-2/
[2] InvenSense Developers Corner http://www.invensense.com/developers/software-downloads
[3] Arduino Zero board https://www.arduino.cc/en/Main/ArduinoBoardZero
[4] J-Link Debug Probes https://www.segger.com/jlink-debug-probes.html
[5] Eclipse IDE for C/C++ Developers https://eclipse.org/downloads/
[6] Arduino IDE https://www.arduino.cc/en/Main/Software
Table 1
1.3. TERMINOLOGY
FireFly Device InvenSense SoC Device, e.g. ICM-30630
FireFly EMD Acronym for FireFly Embedded Software Packages
FireFly SDK Software package containing items for development of new elements to be embedded on the FireFly SoC.
Custom Sensor Designer Design your code that you will be able to load on the FireFly MCU, using outputs of sensors integrated in the Sensor Framework. SensorStudio can also run this code on the desktop CPU.
Auxiliary Sensor Designer Design the sensor driver code you will be able to load on FireFly MCU. SensorStudio cannot run this code on the desktop CPU.
Custom Sensor Custom Sensor is the user-defined code that has been loaded and running on the FireFly MCU.
Block A block is a piece of software, processing inputs and generating outputs. A block
has one or multiple input pins exports one or multiple output pins exposes properties
SensorStudio User Documentation
Document Number: AN-000078 Page 7 of 47 Revision: 1.0 Date: 10/28/2015
Plugin It contains multiple blocks for a common usage. For instance, the IOFile plugin contains all blocks related to IO file operations like reading a file, writing a line, etc. InvenSense SensorStudio comes with a wide range of plugins to access device sensors, perform math operations, signal processing, etc.
Flow A Flow is composed of different blocks from different plugins connected to each other
SensorStudio User Documentation
Document Number: AN-000078 Page 8 of 47 Revision: 1.0 Date: 10/28/2015
2 SCOPE
2.1 OVERVIEW
InvenSense SensorStudio is the software companion to the FireFly family chipset, designed to simplify the work involved in adding sensors and data fusion to your products. With InvenSense SensorStudio connected to evaluation boards, you will be able to select and evaluate the FireFly embedded features you are interested in (orientation, activity tracking, gestures, etc). With InvenSense SensorStudio connected to your development boards, you will also be able to design and validate your own embedded features. InvenSense SensorStudio simplifies configuring and extending FireFly SensorHub Framework. InvenSense already supports many partners’ sensors, yet if your project requires an unsupported sensor, a complete API is provided to support the SensorHub Framework extension. For a hands-on learning experience, please refer to the Quick Start Guide (see 3) section. The Reference Manual (see 4) sections is a summary of the SensorStudio capabilities. Also, the Help window (see 4.4) is always there to give you detailed and contextual information.
SensorStudio User Documentation
Document Number: AN-000078 Page 9 of 47 Revision: 1.0 Date: 10/28/2015
3 QUICK START GUIDE
3.1 OVERVIEW
InvenSense SensorStudio is the software companion for the InvenSense FireFly chipset, helping to support programming the InvenSense FireFly MPU and visualizing its outputs. This section will guide your step-by-step guide through your first use of InvenSense SensorStudio with FireFly SoC. You will learn how to:
- Visualize FireFly outputs with InvenSense SensorStudio - Program FireFly and visualize outputs of your own software
SensorStudio User Documentation
Document Number: AN-000078 Page 10 of 47 Revision: 1.0 Date: 10/28/2015
3.2 INSTALLING SENSORSTUDIO
You will need to create an account on InvenSense Developers Corner to download SensorStudio from the Software Downloads section. Once the download is complete, start the SensorStudio installer by double clicking on the InvenSenseStudio-win32-2.0.0-setup.exe file. An installer wizard will guide you through the installation steps as follows:
Figure 1. Screenshot of InvenSense SensorStudio Setup Wizard
You will then be prompted to review and accept our End User License Agreement:
Figure 2. Screenshot of InvenSense SensorStudio Setup Wizard EULA
SensorStudio User Documentation
Document Number: AN-000078 Page 11 of 47 Revision: 1.0 Date: 10/28/2015
The Installer Wizard then suggests a default installation path:
Figure 3. Screenshot of InvenSense SensorStudio Setup Wizard install path
You may then elect to add SensorStudio to Windows Start Menu:
Figure 4. Screenshot of InvenSense SensorStudio Setup Wizard start menu
Just tick the “Don’t create a Start Menu Folder” option otherwise, and press “Next”.
SensorStudio User Documentation
Document Number: AN-000078 Page 12 of 47 Revision: 1.0 Date: 10/28/2015
You may then add a SensorStudio icon on your Windows desktop:
Figure 5. Screenshot of InvenSense SensorStudio Setup Wizard desktop shortcut
Just untick the “Create a desktop icon” option otherwise, and press “Next”. You may start the installation now by just clicking on the “Install” button.
Figure 6. Screenshot of InvenSense SensorStudio Setup Wizard install
SensorStudio User Documentation
Document Number: AN-000078 Page 13 of 47 Revision: 1.0 Date: 10/28/2015
You will be able to the follow the installation process and a progress bar gives you an indication of the overall installation work done.
Figure 7. Screenshot of InvenSense SensorStudio Setup Wizard installing
If you have previously installed the Arduino IDE, SensorStudio installer will inform you:
Figure 8. Screenshot of InvenSense SensorStudio Setup Wizard Arduino driver
Otherwise, the installer will also let you install the Arduino drivers.
SensorStudio User Documentation
Document Number: AN-000078 Page 14 of 47 Revision: 1.0 Date: 10/28/2015
If you have previously installed Microsoft Visual Redistributable, it will prompt you with the option to repair the installation:
Figure 9. Screenshot of Microsoft Visual Redistributable
Otherwise, the installer will also let you install the Microsoft Visual Redistributable.
SensorStudio User Documentation
Document Number: AN-000078 Page 15 of 47 Revision: 1.0 Date: 10/28/2015
Press the “Finish” button once the Microsoft Visual Redistributable is complete.
Figure 10. Screenshot of Microsoft Visual Redistributable complete
The installation is now complete and you may start InvenSense SensorStudio:
Figure 11. Screenshot of InvenSense SensorStudio Setup Wizard complete
Just untick the “Launch InvenSense SensorStudio” if you want to use SensorStudio later.
SensorStudio User Documentation
Document Number: AN-000078 Page 16 of 47 Revision: 1.0 Date: 10/28/2015
3.3 CONNECTING FIREFLY
InvenSense SensorStudio supports the connection with the ICM-30630 Arduino shield using an Arduino Zero. Details about the ICM-30630 Arduino shield configuration are provided in the “ICM-30630-eMD_Software User Guide” and “Application Note: Eclipse J-Link debugging ICM30630”. For this document, we are assuming all the prerequisite steps have been performed:
- The Arduino Zero, the InvenSense ICM-30630 Shield, and InvenSense Sensor DaughterBoard are connected to the PC through a USB port
- The J-Link Base debugger is connected to InvenSense ICM-30630 Shield using the debug cable (flat grey and red cable) - The J-Link Base debugger is connected to the PC through a USB port
Below is a picture of the hardware configuration we will use in this quick start guide:
Figure 12. Picture of ICM30630 DK and J-Link probe
SensorStudio User Documentation
Document Number: AN-000078 Page 17 of 47 Revision: 1.0 Date: 10/28/2015
3.4 EVALUATING FIREFLY
InvenSense SensorStudio installer may have created a shortcut on your Windows desktop and/or Windows start menu and/or Windows Toolbar.
Start InvenSense SensorStudio by double clicking on the shortcut. If you elected not to add shortcuts during the install process, you can still locate an InvenSense SensorStudio shortcut where you installed the software (e.g. default install path is C:\InvenSense\InvenSenseStudio\2.0.0). At startup time, InvenSense SensorStudio will bring up the “Welcome screen“
Figure 13. Screenshot of Welcome Screen, Get Started tab
SensorStudio is verifying if a new version is available for download from our Developers Corner. You will notice an “Update available” on SensorStudio Welcome screen when a new version exists. Please select the “About Orientation” sample from the “Get Started” tab. This will open up InvenSense SensorStudio main window and look as follows.
Figure 14. Screenshot of FireFly Orientation sample
SensorStudio User Documentation
Document Number: AN-000078 Page 18 of 47 Revision: 1.0 Date: 10/28/2015
The “About Orientation” code sample can be controlled via push buttons that have been added to the flow. The “Start/Stop” push button simplifies several InvenSense SensorStudio actions into 1 single click.
Figure 15. Screenshot of FireFly Start/Stop Push Button
Pressing the “Start/Stop” push buttons executes a LUA script and performs the following actions:
- Tick the “Connected” property of the ICM-30630 device block .
- Tick the “Enabled” property of the RotationVector feature block
- Tick the “Enabled” property of the GameRotationVector feature block
- Tick the “Enabled” property of the GeomagRotationVector feature block
- Tick the “Enabled” property of the Magnetometer feature block
- Tick the “Enabled” property of the Accelerometer feature block
- Tick the “Enabled” property of the Gyrometer feature block - Start the InvenSense SensorStudio flow execution.
You should notice the InsenSense SensorStudio “Play toolbar” is now showing the running icon , while it was previously
showing the “Play” icon .
You shall see the various cubes rotate in space as you rotate your Arduino board. Please note, ICM-30630 block “Connected” property is loading and starting the Sensor Framework in FireFly SoC. “Enabled” of the various features block, and starting the SensorStudio flow execution then allows the SensorStudio runtime to run on the desktop and process outputs from ICM-30630. For more information on this, please refer to 3.7 Sensor Framework explained.
SensorStudio User Documentation
Document Number: AN-000078 Page 19 of 47 Revision: 1.0 Date: 10/28/2015
You can also “single click” on ICM-30630 device and observe the “Connected” property is ticked:
Figure 16. Screenshot of ICM30630 Properties Window
You will notice the Help window is now showing the contextual help related to the select ICM-30630 device block.
Figure 17. Screenshot of ICM-30630 Help Window
You can “single click” on each block available in the flow to review the Help window content and get more familiar with these elements.
SensorStudio User Documentation
Document Number: AN-000078 Page 20 of 47 Revision: 1.0 Date: 10/28/2015
You can repeat the above steps for each of the default features our FireFly SoC supports by default. You can find the list of features supported by your FireFly ICM-30630 SoC through the “Available Sensors” property list:
Figure 18. Screenshot of ICM-30630 properties (AvailableSensors)
You can always bring up the Welcome Screen again from:
Figure 19. Screenshot of Help menu/Welcome Item
SensorStudio User Documentation
Document Number: AN-000078 Page 21 of 47 Revision: 1.0 Date: 10/28/2015
3.5 CREATE A FLOW
In this section, you will learn how to create your own flow and visualize the outputs from InvenSense sensor framework that is running on FireFly SoC.
To start fresh in InvenSense SensorStudio, left click on the icon to create a “New Empty Flow” in SensorStudio. Now let us start the flow creation process by adding a device. Enter “icm” in the “Pool” window search field and notice the ICM30630 block from the list, as shown below.
Figure 20. Screenshot of Search for ICM device block in Pool Window
For more information about the Pool window, please refer to “4.6 Pool window” section. Left click and hold on ICM30630 to drag and drop the ICM30630 on the flow area
Figure 21. Screenshot of ICM30630 added to Flow area
Repeat the “Left click and hold” on to drag and drop the Accelerometer, Gyroscope and GameRotationVector blocks on the flow area, to obtain the following
Figure 22. Screenshot of Flow with Accelerometer, Gyroscope & GameRotationVector blocks
SensorStudio User Documentation
Document Number: AN-000078 Page 22 of 47 Revision: 1.0 Date: 10/28/2015
Left click on the ICM30630 output , hold and move your mouse to the input of the Accelerometer block (until the mouse cursor becomes a “+” sign), to create a connection between the blocks. Repeat this operation between ICM30630 & Gyroscope, and ICM30630 & GameRotationVector. You will obtain the following:
Figure 23. Screenshot of Flow connections between ICM30630 device and its Sensor Framework features
Enter “Sliding” in the “Pool” window search field and notice the ICM30630 block from the list
Figure 24. Screenshot of Sliding Panel in Pool Window
Left click on the “Sliding” list item, hold, drag and drop 2 “Sliding” panel on the flow. Create connections between the Accelerometer ‘data’ output and the 1
st Sliding panel, and between the Gyroscope ‘data’ output and 2
nd Sliding panel, as follow:
Figure 25. Screenshot of Flow with Sliding for Accelerometer & Gyroscope
You may have noticed a mouse hover the block’s outputs or inputs, create an overlay with the brief description
SensorStudio User Documentation
Document Number: AN-000078 Page 23 of 47 Revision: 1.0 Date: 10/28/2015
You may also have noticed all the elements you have added to the flow are also listed in the “Flow window”:
Figure 26. Screenshot of Flow window
Now, left click on the ICM30630 block and make sure the “Connected” property is ticked
Figure 27. Screenshot of Connected ICM30630
Left click on the Accelerometer block and make sure the “Enabled” property is ticked, and repeat this for the Gyroscope. Now you are ready to start the InvenSense SensorStudio flow execution and the Sensor Framework in FireFly. Left click on the Play
button on the “Play toolbar” . The “Play Toolbar” is now showing the “Stop” icon and the “Curves” panel on the flow is now receiving outputs from sensor framework running in FireFly
Figure 28. Screenshot of Running FireFlySensor Framework and SensorStudio Flow
SensorStudio User Documentation
Document Number: AN-000078 Page 24 of 47 Revision: 1.0 Date: 10/28/2015
The GameRotationVector block output is a Quaternion. The “Cube” panel’s input is expecting a RotationMatrix, so we will need to add a “QuaternionToRotMatrix” conversion block in between, as follow:
Figure 29. Screenshot of GRVector block & Cube Panel to Visualize FireFly Device Orientation in Space
Now you can save your flow using the “File” menu, “Save As” menu item (or Ctrl+Shit+L)
Figure 30. Screenshot of File Menu Save As…
You will get a File Name selection window.
SensorStudio User Documentation
Document Number: AN-000078 Page 25 of 47 Revision: 1.0 Date: 10/28/2015
3.6 DESIGN YOUR SENSOR ALGORITHM
In this section you will learn how to add an algorithm, written in C code, to the InvenSense sensor framework running on FireFly SoC. The first step to create your algorithm is to add a CustomSensorDesigner block to the flow and connect it to the output of the sensors fusion supported by ICM30630 device. For this example, we will use the output of the GameRotationVector block:
Figure 31. Screenshot of Add CustomSensorDesigner to create your algorithm in C code
Left click on the CustomerSensorDesigner block to select it, and click on the button “…” of the “ImplCode” property of the “Properties” window.
Figure 32. Screenshot of CustomSensorDesign Properties
This will bring up the C Editor, where you will notice that, for the block creation, a code skeleton has been provided by default, so the algorithm creation process is simplified.
Figure 33. Screenshot of CustomSensorDesign C Editor
The skeleton code serves as a reminder of the APIs a CustomSensor code has to implement in order to integrate smoothly in the FireFly Sensor Framework.
SensorStudio User Documentation
Document Number: AN-000078 Page 26 of 47 Revision: 1.0 Date: 10/28/2015
For this example to be educational, we will keep the code very simple and just try to use the yaw angle, detect a 30° horizontal rotation of the board, and report a Door Opened/Closed message.
Figure 34. Picture of ICM30630 Arduino horizontal rotation
We will start with the init() function. The beginning of the provided skeleton code follows, and we replaced the skeleton code with the following, including declarations and init() code
Figure 35. Screenshot of Original Skeleton Code Versus DoorOpeningDetection Code for init()
You can leave the subscribe_event(), unsubscribe_event(), period_event() and game_rotation_vector_period_event() functions unmodified as we don’t want to customize their behavior in this simple code. Modify the game_rotation_vector_data_event() function as follow:
Figure 36. Screenshot of Original Skeleton Code versus DoorOpeningDetection code for data_event()
The complete list of data types and functions available for you to use in your CustomSensor code are listed in the ‘Extension
Framework Documentation’, please refer to “3.7 Sensor ” or click on the “API Documentation” button of your
CustomSensorDesigner “C Editor”.
SensorStudio User Documentation
Document Number: AN-000078 Page 27 of 47 Revision: 1.0 Date: 10/28/2015
Now that we are done with coding, we need to define the data type format of the CustomSensor output for the flow (that should be consistent with the notify() calls from you code).
Figure 37. Screenshot of CustomSensorDesign Properties Format
The complete list of data type format available for use in the CustomSensor output can be obtained by selecting the Format field:
Figure 38. Screenshot of CustomSensor Properties Format selection
The Help window will then show all the options available:
Figure 39. Screenshot of CustomSensor Properties Format help
SensorStudio User Documentation
Document Number: AN-000078 Page 28 of 47 Revision: 1.0 Date: 10/28/2015
Everything is now ready to build the code for FireFly; and this is just 1 click button away:
Figure 40. Screenshot of FireFly toolbar Build button
This will bring up the
Figure 41. Screenshot of “Build and flash” configuration
You may select “Optional Sensors” from the list. This will configure the FireFly Sensor Framework accordingly with the selected features/sensors. Press the “Next” button will start the build process.
Figure 42. Screenshot of “Build and flash” window successful build
If the build is not successful, you will get GCC compiler warnings and errors details listed in the status area.
SensorStudio User Documentation
Document Number: AN-000078 Page 29 of 47 Revision: 1.0 Date: 10/28/2015
Following a successful build you can press the “Flash” button; this brings up the Flash window as follow:
Figure 43. Screenshot of FireFly “Flash” window
Upon successful FireFly flashing, you can now close the “Flash” window. You can verify the name of the firmware is no longer the default name but now corresponding to the name you previously entered in Build Config windows:
Figure 44. Screenshot of ICM30630 Firmware Image Path
Please make sure to tick the ICM30630 “Connected”, the GameRotationVector “Enabled” and CustomSensor “Enabled” properties before you start the flow (F9 keyboard shortcut). Now that your CustomSensor code has been loaded and is running in FireFly, you can visualize its output via a Color panel.
The Color panel will change color, when preforming a yaw angle (flat rotation) of the ICM30630 board of more than 30°, as per game_rotation_vector_data_event() function implementation seen before.
SensorStudio User Documentation
Document Number: AN-000078 Page 30 of 47 Revision: 1.0 Date: 10/28/2015
The final project is available from the SensorStudio Welcome Screen
Figure 45. Screenshot of Door Opening Detection sample
Additional information and visual elements have been added to the complete flow. Please make sure to tick the ICM30630 “Connected”, the GameRotationVector “Enabled” and CustomSensor “Enabled” properties before you start the flow. You will notice the “image” panel is being used to display the “Opened Door” and “Closed Door” image files, depending on the output of the CustomSensor ID #0. Left click on the image panel and click on the “…” button of its “Properties” window:
Figure 46. Screenshot of Image Panel
You will notice that both the “CustomerSensorDesigner” output and the “CustomSensor” ID #0 output are being displayed. This shows that the same DoorOpenDetection code can be running embedded in FireFly MCU (“CustomSensor block”) and in the desktop CPU, at the same time. This can be useful to speed up the algorithm development time, as running embedded always requires additional build and flash steps.
SensorStudio User Documentation
Document Number: AN-000078 Page 31 of 47 Revision: 1.0 Date: 10/28/2015
3.7 SENSOR FRAMEWORK EXPLAINED
The Sensor Framework includes a communication mechanism to notify about and subscribe to produced data. Creating your CustomSensor code, with CustomSensorDesigner block, involves understanding the basic operation of InvenSense Sensor Framework.
– Your CustomSensor init() function is called once to initialize the state of the custom sensor (after the FireFlydevice is powered up, when sensor framework is started: ICM30630 “Connected” property)
– Your CustomSensor period_event() function is called just before your custom sensor is started. This allows you to configure the frequency of your subscribed sensors (like accelerometer). Studio implements this by default, you may change this to implement decimation on all sensors at once.
– Your CustomSensor subscribe_event() function is called by Sensor Framework when enabling the sensor. It lets you register your sensor dependencies to the Sensor framework. Studio implements this by default (all visual connections are already taken into account).
– Your CustomSensor game_rotation_vector_data_event() function is called upon receiving a new sensor data of a given type. You will have as many XYZ_data_event() functions to implement as you have subscribed sensors. This is the place to store and process your data (just replace game_rotation_vector_ by other sensor data type). When you are done with your processing, use the notify() function to pass on your produced data.
– Your CustomSensor game_rotation_vector_period_event() function is called when the period of the given subscribed sensor is changed. You may implement this function if you have subscribed sensors running at difference frequencies. Studio implements this by default, you may change this to implement decimation on the given sensor.
– Your CustomSensor unsubscribe_event() function is called by Sensor Framework when disabling the sensor. It lets you unregister your sensor dependencies to the Sensor framework. Studio implements this by default (all visual connections are already taken).
Figure 47. Sensor Framework overall operation diagram
The complete list of APIs and detailed documentation of the Sensor Framework is provided in the “Doc” folder of you SensorStudio install, look for the ‘Extension Framework Documentation’ link, or directly from the C Editor of the CustomSensorDesigner block.
SensorStudio User Documentation
Document Number: AN-000078 Page 32 of 47 Revision: 1.0 Date: 10/28/2015
You may need to pay some special attention to the input frequencies of your CustomSensors and how you deal with incoming data from the other Sensors, depending on your application needs. We have seen before in this section, the Sensor Framework relies on a communication mechanism, based on subscribe & notify messages. In case several CustomSensors subscribe to a given Sensor and specify different frequencies, the Sensor Framework will ensure this given Sensor is programmed to produce data at the faster data rate. For example, two CustomSensors could request Accelerometer Sensor data at different frequencies: - CustomSensor A at 10Hz - CustomSensor B at 100Hz The Sensor Framework would adjust the accelerometer to 100Hz and it would be up to the CustomSensor A to decimate or cope with incoming data at a faster rate. The DoorOpeningDetection code sample has been designed to provide a working exemple of decimation, please report to the period_event() and game_rotation_vector_period_event() functions. You should also note the Sensor Framework ensures the Sensor data output is decimated so the Application processor is getting the specified frequency. You might want to double check the Sensor frequency and how you are implementing the period_event(), in case, you may experience different behaviors between your CustomSensor running embedded in FireFly MCU (“CustomSensor block”) and your CustomSensor running in the desktop CPU.
SensorStudio User Documentation
Document Number: AN-000078 Page 33 of 47 Revision: 1.0 Date: 10/28/2015
3.8 DESIGN YOUR SENSOR DRIVER
FireFly Sensor Framework comes with pre-integrated sensors: magnetometer, proximity, temperature, pressure. These sensors are available as options of the Firmware build window (please refer to Figure 41. Screenshot of “Build and flash” configuration). You may also add your own new sensor type to the FireFly Sensor Framework, using the AuxiliarySensorDesigner block. This section of the document will guide you in doing so. Before getting into the creation details, it is important to note the AuxiliarySensorDesigner is somewhat similar but different from the CustomSensorDesigner block discussed in sections 3.6 & 3.7. Both blocks support creating code that integrates the FireFly Sensor Framework, which you can access through a CustomSensor block, the difference between those blocks lies in:
- CustomSensorDesigner block is software that depends & process other sensors outputs to create its own outputs - CustomSensorDesigner block is software that does not access hardware directly (code can be run within SensorStudio
desktop executable) - AuxiliarySensorDesigner block is software that doesn’t depends & process other sensors outputs - AuxiliarySensorDesigner block is software that access hardware directly to create its own outputs (code cannot be run
within SensorStudio desktop executable) Now let us dive in the creation details; just look up for the AuxiliarySensorDesigner block from the Pool window:
Figure 48. Screenshot of AuxiliarySensorDesigner in Pool window
Drag and drop the AuxiliarySensorDesigner block onto the flow area (left click & hold on the AuxiliarySensorDesigner block from the Pool window; move to the flow area and release the left click button to place the AuxiliarySensorDesigner block close by the ICM30630 block). Add a corresponding CustomSensor block and create the block connections on the flow area as follow:
Figure 49. Screenshot of AuxiliarySensorDesigner flow
Default code for reading a 3rd-party Magnetometer is provided when creating a new AuxiliarySensorDesigner, just to help you and serve as a working sample. You can access the AuxiliarySensorDesigner code thru the ImplCode “…” button of the block Properties window:
Figure 50. Screenshot of AuxiliarySensorDesigner Properties
SensorStudio User Documentation
Document Number: AN-000078 Page 34 of 47 Revision: 1.0 Date: 10/28/2015
This will bring up the C Editor window:
Figure 51. Screenshot of AuxiliarySensorDesigner Code Sample
The complete list of APIs and detailed documentation of the Sensor Framework is provided directly from the C Editor “API Documentation”. We will now review the APIs you need to implement your own sensor driver. Scroll down the C Editor windows and locate the write_reg_hook() function:
Figure 52. Screenshot of AuxiliarySensorDesigner code sample I2C read/write
inv_shext_aux_i2c_write_reg() is used to Write register over Auxiliary I2C bus and inv_shext_aux_i2c_read_reg() is used Read register over Auxiliary I2C bus. These are the basis for your access to your hardware.
SensorStudio User Documentation
Document Number: AN-000078 Page 35 of 47 Revision: 1.0 Date: 10/28/2015
Now, locate the MyCustomTaskCode() function. This task will be your own task, responsible for polling data from your sensor at a specified Period.
Figure 53. Screenshot of AuxiliarySensorDesigner code sample MyCustomTaskCode()
Therefore MyCustomTaskCode() implementation :
- Gets current system time in tick using inv_shext_get_systick(), for later timestamping purpose. - Retrieves new samples from your sensor (see ak09911_get_sample() implementation). - It then uses the notify() function to share the produced data with other CustomSensor code, that might be using it. - Finally it triggers a new acquisition, so next time the MyCustomTaskCode() is called, the sensor data will be ready to read.
During the Sensor Framework init(), you will initialize your task MyCustomTask using inv_shext_task_create()
Figure 54. Screenshot of AuxiliarySensorDesigner Code Sample init()
SensorStudio User Documentation
Document Number: AN-000078 Page 36 of 47 Revision: 1.0 Date: 10/28/2015
On subcribe_event(), you will need to start your task MyCustomTask using inv_shext_task_start()
Figure 55. Screenshot of AuxiliarySensorDesigner Code Sample subscribe_event()
And on period_event(),you will need to define the period at which your task MyCustomTaskCode will be called using inv_shext_task_set_period()
Figure 56. Screenshot of AuxiliarySensorDesigner Code Sample period_event()
SensorStudio User Documentation
Document Number: AN-000078 Page 37 of 47 Revision: 1.0 Date: 10/28/2015
4 SENSORSTUDIO REFERENCE MANUAL
4.1 MAIN SCREEN
InvenSense SensorStudio is a graphical User Interface supporting development of sensor data fusion with InvenSense Firefly chipset.
Figure 57. Screenshot of InvenSense SensorStudio with orientation project file opened
In the center you find the Flow section, A. It is the core of InvenSense SensorStudio where you can design your feature by adding
and linking different blocks together and by so composing flows. Here we see the orientation.flow graph. It starts with ICM30630 Sensors blocks, providing sensors fusion orientation ouputs. Then different blocks are plugged to deliver at the end an AG, AM and AGM orientation with the Cube panels. We can also see some visualization objects within our scene: they are called Panels.
From B, you have access to a pool of plugins, each plugin containing several blocks / panels which you can drag in the flow section.
Each block is explained in the Help section, D.
Also you can view and edit filter properties, once selected, in the Properties section C In the command menu bar, there is an FireFly Toolbar, E, which allows InvenSense SensorStudio desktop to control an ICM30630
device.
A
C
B
D
E
SensorStudio User Documentation
Document Number: AN-000078 Page 38 of 47 Revision: 1.0 Date: 10/28/2015
4.2 FIREFLY
You may use the FireFly toolbar buttons .to manage your FrieFly SoC device. The FireFly toolbar status area will give you the identification of the device when connected (e.g. ICM 30630
) or it will show “NO DEVICE” when disconnected (e.g. )
The “Device Information” button brings up windows with the device name and firmware revision.
The “Build firmware” button brings up the “Build and flash” window:
Figure 58. Screenshot of “Build and flash” configuration
You may specify a new name for the firmware image and select “Optional Sensors” from the list. This will configure the FireFly Sensor Framework accordingly with the selected features/sensors. Press the “Next” button when the configuration is done to start the build process.
Figure 59. Screenshot of “Build and flash” window successful build
If the build is not successful, you will get GCC compiler warnings and errors details listed in the status area.
SensorStudio User Documentation
Document Number: AN-000078 Page 39 of 47 Revision: 1.0 Date: 10/28/2015
The “Flash Device” button brings up the Flash window:
Figure 60. Screenshot of FireFly “Flash” window
All the actions of the FireFly toolbar are also listed in the FireFly menu:
Figure 61. Screenshot of FireFly menu
SensorStudio User Documentation
Document Number: AN-000078 Page 40 of 47 Revision: 1.0 Date: 10/28/2015
4.3 FLOW AREA
You may use the View toolbar buttons to “Zoom In” or Zoom Out” and adjust the flow area zoom level to your convenience. You may use the “Fit in view” button to let SensorStudio find the zoom level and centering of the view so you can see all your design elements at once. The “Zoom In”, “Zoom Out” and “Fit in view” actions are also available from the View menu:
Figure 62. Screenshot of InvenSense SensorStudio View Menu
Left click and hold on the view area allows you to move around the content of the flow area as you wish when working on your project. Just release the click when the position suits your need.
4.4 HELP WINDOW
The Help window is contextual, meaning it is related to the selection in the flow area, e.g. click on ICM-30630 device block.
Figure 63. Screenshot of ICM-30630 Help Window
SensorStudio User Documentation
Document Number: AN-000078 Page 41 of 47 Revision: 1.0 Date: 10/28/2015
The Help window context can also be set to show further details of the options available for any property of the Properties window, e.g. click on the “Format” property of the CustomSensorDesign Properties window :
Figure 64. Screenshot of CustomSensorDesign Properties Format help
The Help context is highlighted in light blue color either in the flow area (e.g. ) and in the
Properties Windows when applicable (e.g. ).
4.5 PROPERTIES WINDOW
The Properties window is also contextual, meaning it is related to the selection in the flow area, e.g. click on ICM-30630 device block
Figure 65. Screenshot of ICM30630 Properties window
Use the Help window to find out more details about any given property.
SensorStudio User Documentation
Document Number: AN-000078 Page 42 of 47 Revision: 1.0 Date: 10/28/2015
4.6 POOL WINDOW
InvenSense SensorStudio pool window lists all software components available.
Figure 66. Screenshot of Pool Window
The software components are called SensorStudio plugins and there are 2 types of plug-ins :
are groups of processing elements designed to compute various things, from basic matrix, arrays operations, to more complex high-level functionalities. By default these processing elements run within SensorStudio desktop CPU.
are groups of visualization elements, called Panels, designed to display various things, from basic text, to more advanced graphics. The “filter” field allows you to enter part of the block you might be looking for, and perform a search from the blocks & panels Pool window:
Figure 67. Screenshot of AuxiliarySensorDesigner in Pool window
SensorStudio User Documentation
Document Number: AN-000078 Page 43 of 47 Revision: 1.0 Date: 10/28/2015
4.7 FLOW WINDOW
InvenSense SensorStudio Flow window provides you a list view of the elements present in your project (while the Flow area is a graphical view).
Figure 68. Screenshot of Flow window
In the Flow window of the Orientation sample above, we can find the various blocks (ICM30630 device; GameRotationVector, GeomagRotationVector & RotationVector sensors; and various computing blocks to transform the quaternion outputs into Euler angles).
The Play button will start the Flows. SensorStudio runtime will traverse the graph, in order, from the device outputs and progressing, executing each computing block one at a time, within 1 Flow. Each Flow is executed in an independent thread. The graph traversal is repeated based on the MinPeriod property value of the corresponding Flow. Depending on your project complexity, you may have chose to create different Flows running within different threads, using the
Create Flow button .
You should notice the InvenSense SensorStudio “Play toolbar” is now showing the running icon , while it was previously
showing the “Play” icon . Consistently, the Play button in the Flow window has transformed into a Stop button . These actions are also available from the Run menu and supports keyboard shortcuts as follow
Figure 69. Screenshot of Flow menu
The Step-By-Step button will start the Flows execution one step at a time. In this case, the Flows are executed once, and the graphs are traversed from the device outputs, following the graph’s ordering, processing one block at a time, until all blocks have
been executed once, then stop. You may execute another Flow step using the Step By Step button again.
SensorStudio User Documentation
Document Number: AN-000078 Page 44 of 47 Revision: 1.0 Date: 10/28/2015
4.8 LUA SCRIPT
LUA scripting is an efficient way to automate several manual actions in a single click push button interface.
You may add this push button to your Flow searching the Pool window for the ButtonInput panel Using the Orientation sample, accessed from the Welcome Screen, you will easily notice and select the Start/Stop ButtonInput
You can then click on the “…” button of its Script property
Figure 70. Screenshot of ButtonInput Properties
This will bring up the Lua Editor window with a working example of code
Figure 71. Screenshot of Lua Editor
The code above is - Tick the “Connected” property of the ICM-30630 device block . - Tick the “Enabled” property of the RotationVector feature block - Tick the “Enabled” property of the GameRotationVector feature block - Tick the “Enabled” property of the GeomagRotationVector feature block - Start the InvenSense SensorStudio “Main” flow execution.
SensorStudio User Documentation
Document Number: AN-000078 Page 45 of 47 Revision: 1.0 Date: 10/28/2015
When a new ButtonInput panel is created, it comes by default with sample code as follow, to help you create your script
Figure 72. Screenshot of Lua Script Default Code Sample
SensorStudio User Documentation
Document Number: AN-000078 Page 46 of 47 Revision: 1.0 Date: 10/28/2015
3. REVISION HISTORY
REVISION DATE
REVISION DESCRIPTION
10/28/2015 1.0 Initial Release
SensorStudio User Documentation
Document Number: AN-000078 Page 47 of 47 Revision: 1.0 Date: 10/28/2015
This information furnished by InvenSense is believed to be accurate and reliable. However, no responsibility is assumed by InvenSense for its use, or for any infringements of patents or other rights of third parties that may result from its use. Specifications are subject to change without notice. InvenSense reserves the right to make changes to this product, including its circuits and software, in order to improve its design and/or performance, without prior notice. InvenSense makes no warranties, neither expressed nor implied, regarding the information and specifications contained in this document. InvenSense assumes no responsibility for any claims or damages arising from information contained in this document, or from the use of products and services detailed therein. This includes, but is not limited to, claims or damages based on the infringement of patents, copyrights, mask work and/or other intellectual property rights. Certain intellectual property owned by InvenSense and described in this document is patent protected. No license is granted by implication or otherwise under any patent or patent rights of InvenSense. This publication supersedes and replaces all information previously supplied. Trademarks that are registered trademarks are the property of their respective companies. InvenSense sensors should not be used or sold in the development, storage, production or utilization of any conventional or mass-destructive weapons or for any other weapons or life threatening applications, as well as in any other life critical applications such as medical equipment, transportation, aerospace and nuclear instruments, undersea equipment, power plant equipment, disaster prevention and crime prevention equipment. ©2015 InvenSense, Inc. All rights reserved. InvenSense, Sensing Everything, MotionTracking, MotionProcessing, MotionProcessor, MotionFusion, MotionApps, DMP, and the InvenSense logo are trademarks of InvenSense, Inc. Other company and product names may be trademarks of the respective companies with which they are associated.
©2015 InvenSense, Inc. All rights reserved.
