Getting Started With TapNLink
Part I: End user features overview
- Primer Kit
- To be supplied by the client:
- 5V power cable (micro USB)
- Android or iOS smartphone
To get an overview of TapNLink features, follow these steps:
- Connect the TapNLink Primer to the target board’s SWD/JTAG port.
- Power the target application.
- Activate smartphone connections.
- Install the Tap Manager app.
- Launch the Tap Manager app.
- Monitoring the Sensor Demo application.
- Register with IoTize Primer Cloud Services.
- View your Primer configuration from the Cloud.
- Start data logging.
1. Connect TapNLink Primer to target board’s SWD/JTAG port
The purple cable is not required for this demo. It is used for the S3P Secure Software Serial Protocol. Refer to S3P Application Note.
2. Power target application
- Power the STM32 target board with a micro USB power cable: its red LED lights up and the green LED starts blinking. The target board powers the TapNLink.
3. Activate smartphone connections
- Activate Bluetooth mode
- Activate a data service (2.5G/3G/3.5G …) or WIFI access
- Activate NFC mode if it's available
4. Install Tap Manager App
On an Android Device
If you have an Android smartphone fitted with an NFC reader:
- Determine where the NFC antenna is located on your smartphone (refer to the FAQ for details)
- ‘tap’ your smartphone on your Tap
- Install and open the Tap Manager app that appears in Google Play.
Otherwise, install the app manually from Google Play Store:
During installation, give access to:
- Location data (IoTize does not use this data, but some Androids need it for BLE).
- Internal files.
- Bluetooth / BLE (Bluetooth low energy).
Note : if you received TapNLink Primer prior to July 2018, the IoTize app is ICS and not Tap Manager (refer to the FAQ for details).
On an iOS Device
- You can install Tap Manager for iOS from Apple App Store.
- Tap Manager requires iOS 12.0 or newer. For using NFC\BLE pairing features you will need an iPhone 7, 8 or X. The current XS, XS Max and XR iPhones can also scan NFC tags and launch automatically Tap Manager when scanning a Tap Device.
5. Launch Tap Manager App
- If you have a smartphone with NFC (near field communication) tap the TapNLink Primer again.
- Otherwise, launch Tap Manager manually and select your TapNLink from the available BLE devices.
Your smartphone can connect with the TapNLink using BLE and NFC. The sensor demo application can work without NFC (by pairing in BLE), but is pre-configured to use BLE+ NFC:
- NFC for pairing (for a better selectivity).
- BLE for transmission (exchange of requests / answers).
6. Monitor Sensor Demo application
After Tap Manager is launched, it displays the data that you have chosen to monitor.
The TapNLink Primer has been pre-configured with 2 profiles: anonymous and tech.
The anonymous profile monitors four variables (read only) and does not require a login:
- temperature (represented as a gauge)
The tech profile has read/write access to additional variables. Touch and hold a second on the upper right-hand User icon to change profile, and enter the following credentials (login: user, PW: user). Proposed manipulations:
- Increase the temperature, for example by pressing your finger on the target board's STM32 MCU and view this change in real-time on the monitoring page
- Touch the LED monitoring section (lower right hand pane) to access to additional R/W variables
- Blinking mode : On, Off, Toggle
- Blinking period (in ms) used for counting and LED blinking (enter a low value for a faster LED blinking and counting, and reciprocally)
- Getting started 2 describes how to view and modify the corresponding configuration
7. Register with IoTize Primer Cloud Services
Registration with IoTize Primer Cloud Services(storage, display, export etc.) completes the data logging functionalities of your TapNLink Primer.
You can register from the Tap Manager monitoring page on your smartphone.
Click on Cloud Services (bottom right of the page) and enter your email.
The serial number and unique ID (UID) are automatically retreived from the tap. After validating the registration, it is preferable to perform the next steps on a PC.
You will receive a first mail containing a link to confirm your registration. Click on this link and type in your password.
You will receive a second e-mail containing a confirmation code to validate your e-mail.
Type this confirmation code in the corresponding field.
8. View Primer configuration and data from IoTize Primer Cloud Services
Connect to your IoTize Primer Cloud Service account.
Check that your TapNLink Primer appears in the menu My Primers:
Click on your TapNLink Primer to display its dashboard.
In the configuration area, click on View detail to see the configuration bundles.
Bundles are groups of variables that are monitored real-time, and can be logged.
Profiles are assigned to Bundles to give appropriate viewing and updating permission.
Getting started 2 explains these settings in more detail.
The pre-configured Sensor Demo application includes 3 bundles:
- variables: Count (integer), LED Status: 0 (on), 1 (off))
- data logging settings: enabled, 60s logging frequency
- variables: Temperature (float), Voltage
- data logging settings: enabled, 61s logging frequency
- variables: Period (LED blinking, counting), LED Config: 0 (off), 1 (on), 2 (blink)
- data logging settings: disabled
9. Start Data logging
Data logging uses:
- the Tap: to log in the internal memory of the tap the variables that were selected during configuration
- the Tap Manager (Android smartphone): to retrieve logged data from the Tap and to upload it to the IoTize Primer Cloud Services.
By default, data packets are uploaded when you launch the Tap Manager app. To check if data logging is running:
On an Android Device:
swipe the screen from the very left to right to see the Actions menu.
- Click Data logging sub menu, which shows the number of data packets that have been uploaded and the number of packets which have been recorded by the Tap but not yet been uploaded.
- You can stop or restart the uploading process by clicking the Stop/Go button.
On an iOS device
- In order to verify data logging feature you should first change the settings of IoTize Tap Manager to enable development views of the app.Go to 'IoTize Tap Manager' settings and select 'Show Toolbar'.
- Launch 'IoTize Tap Manager' app ad select 'Data Logging' tab:
- which shows the number of data packets that have been uploaded.
- you can stop or restart the uploading process by clicking the Stop/Start button.
Proposed manipulations (preferably from a PC)
- If you are not connected to IoTize Primer Cloud Services, reconnect.
- From the dashboard click on your Tap, then Data logging.
- Click on Graphs icon and select the Sensors tab to view the Temperature and Voltage graphs.
- Select the Count_Status tab.
From the monitoring page on your smartphone, change the LED status to:
- off for 2 minutes.
- on for 2 minutes.
- toggle (and leave it with this setting)
Click Reload to view the effects of these manipulations in IoTize Primer Cloud services
- Quit the Tap Manager app to break the connection between your Tap and the cloud.
- Wait at least 2 minutes.
- Reload your graph to verify the last uploaded value is older than 2 minutes.
- Launch the Tap Manager app again (manually or by tapping your smartphone).
- Refresh the data again.
- Check the graph displays all data, without gaps (including the period when the connection was broken). This is achieved by an internal storage mechanism in your Tap.
You can also try other features such as:
- graphical features: zoom in, zoom out, autoscale: accessible through icons on the upper right-hand of the graphs
- access data in table mode
- export your data in csv...
Part II: Configure TapNLink Primer
These are the same as Getting started part 1, plus a Windows PC
To configure a TapNLink Primer, follow these steps:
- Install IoTize Studio.
- Look at the Sensor Demo configuration.
- Start a relay to connect IoTize Studio with your TapNLink Primer.
- Modify the Sensor Demo configuration.
- Auto-generate HTML pages.
- Add profiles, bundles and variables.
- Set Cloud settings.
- Write config in your Tap.
- Check your changes and Publish.
1. Install IoTize Studio (configuration software)
See IoTize Studio reference manual for details.
2. Observe Sensor Demo configuration
Launch IoTize Studio, the Sensor Demo project loads automatically.
If it doesn't, use File / Open and open the Sensor Demo project in your installation directory (C:\Program Files (x86)\IoTize\IoTize Studio\Examples\Sensors_STM32_Demo\Sensor_demo.iotz)
- ELF pathname: used to retrieve variables/symbols of the target application source files
- SVD / XML pathname: used to retrieve the registers and peripherals of the target MCU
- target protocol: defines the communication mode between your Tap and your target (SWD is the easiest implementation but requires the corresponding port to be enabled, S3P offers more flexibility but is more complicated to implement), see Application Note AN03.
Symbols: at the top of the resources panel (2nd column), expand main.c to view the variables defined in the Sensor Demo application.
- you can add these symbols to a bundle (see LEDConfig, LEDStatus, Temperature_C)
- you can view information about the symbol, for example select LEDConfig to see its size and type (in this case: 8-bit, uchar)
- you can expand the SVD Peripheral List to view the internal registers of the target MCU (the Sensor Demo STM32F103). These symbols can also be added to bundles for monitoring or data logging
Bundles: In IOTZ Explorer, expand the Bundles section and view the 3 bundles used in this configuration example:
- Count_Status and Sensors contain 2 variables and are accessible to the anonymous profile which does not require logon. Click on anonymous in the Count_Status bundle, and see in the detailed settings that access is read only (last option at the bottom of the scren shot)
- Count_Control contains 3 variables and is accessible
- to the anonnymous profile (access in read mode)
- to the tech profile (access in read/write mode)
- Click on the tech profile in the Count_Control bundle, and see that access rights are read, write
- Collapse the Bundles and expand the Tech profile
- 2 aliases have been attached to the profile (user and Paul)
- passwords can be given to aliases and for the parent profile
- in both cases, passwords are not displayed but are hashed
- Data logging settings
- click on the Sensors bundle to view the data logging settings for the Sensor Demo (DataLog Period = 61s, at the bottom of the scree shot)
- if DataLog Period is 0 or blank, logging is disabled
- View the settings attached to the Tap: the Development Tap SN is the Serial Number of your TapNLink Primer, at this stage the serial number is generic (IoTzPr004100000000), it will become the serial number of YOUR Tap when you connect to it
3. Connect IoTize Studio to your Tap
If you are working on a BLE enabled PC with Windows 10 (version v10586 or higher), IoTize Studio could connect directly to your Tap. Otherwise you need to setup a communication relay between your Tap and IoTize Studio.
Direct BLE connection:
Select Studio from the configuration explorer and select BLE as the 'Connection To Tap | Protocol'. With clicking the (...) besides the 'BLE device name\address' IoTize Studio will scan the available BLE devices around you, so you can select and use your Tap.
Non direct connection via Tap Manager
If you can not or do not want to use the BLE communication between IoTize Studio and your Tap, you can setup and use a socket relay on a mobile device through Tap Manager.
a. Start a socket relay on your smartphone and connect to the Tap. For details, see Diverse Tools, Relay
b. Configure IoTize Studio (on your PC) to find the socket relay, and your Tap. For details, see Diverse Tools, Configure IoTize Studio for relay
4. Monitor your target system from IoTize Studio
You can now monitor your target application (Sensor Demo) from IoTize Studio.
Click on Monitor.
Do some manipulations to monitor the changes:
- Increase the temperature of your target board's MCU by placing your finger on it, then view the effect
- Change the LED status by logging in as a user with rights to modify LEDstatus. (Click and logon as user / user)
5. Build your own Web App
There are 2 ways to generate monitoring Apps with the IoTize software suite:
- Build a Web App, that uses IoTize Tap Manager mobile App to communicate with the Tap (quickest and simples way)
- Build your own Custom Mobile App using IoTize development librairies APIs
Refer to Mobile development for other options. Note that the Sensor Demo uses this mode (option IoTize 'Tap Manager' App).
With this mode, you can take advantage of the buil-in App generator to generate automatically your web app. Note that in the Sensor Demo, the App generator has been used to generate the first version of the Web aap. The Web App (html pages) has then been customized (with icons, gauges, ... ) using HTML/css tools. To view the "row" pages generated by the app generator, set the Studio detailed setting Automatic Website generation to Yes.
IoTize Studio automatically update the web app (HTML pages) when you make modifications such as: - addition or removal of variables, - modificatoin of access rights... - variable options such as unit, "formula", number of decimals - page option (related to a bundle) such as page color, page name...
- HTML pages are automatically generated for each bundle / profile association.
- Select a profile in the Profile menu to view the related monitoring "home page".
- The examples below show anonymous with read/write rights and with read only rights to Count_Status bundle.
- In addition to the bundles, a monitoring home page shows a section All variables to displays all the variables (regardless of the bundle they are attached to) .
- You can define home page name which is run when you launch the monitoring application: by default this page corresponds to the anonymous profile.
Note that the HTML page structure (for each profile, with an optional "home page") can easily be customized.
Now monitor the target application (using the "row" HTLM pages) using the auto-generated HTML pages:
- Click on the Monitor button (or on Test > Monitor)
- The page for anonymous profile appears
- Log-in as user / user
- The page for Tech profile appears
- Set LEDconfig = 2 to make it blink
- Click on Disconnect to stop monitoring
You can also monitor the "customized Web" (pages with gauges) app of Sensor demo, by toggling back the option Automatic Website generation to No. Note that in this case: - the HTML pages tree structure can be entirely customized. - you have to define the entire path to the "home page" of the Web App
6. Add profiles, bundles and variables
- From menu Add > New profile, create a profile named expert
- In the detailed profile settings:
- Provide a Password, for example expert (the displayed password is hashed)
- Set a Window Color for the related HTML page
Create a new bundle named Temp_int from menu Add > New bundle
Drag and drop expert into the Temp_int bundle (which automatically gives read/write access)
Drag and drop symbols Temperature_mC_sl and Temperature_Average_mC_sl from the Ressouces View window into the Temp_int bundle. If the Resouces View is not displayed, use menu View > Toolbars and Docking Windows to make it appear again. Both symbols measure temperature, (the first is an instant value, the second is an average value) and both are integers (contrary to Temperature in sensors which is a float).
- Define aliases to shorten the names in the auto-generated pages, for example temp_avg for variable Temperature_Average_mC_sl.
- The auto-generated HTML page is updated after each modification (if not, turn monitoring off !)
In the Symbols View, collapse main.C and expand SVD Peripheral File.
Drag and drop the symbol GPIOC.ODR (internal register) into the Temp_int bundle. The content of this register is similar to the "C variable" LED status, with a small time-shift
Change the auto-generated HTML page settings (for example for the variable LED Config).
- set Display in HTML to Yes.
- set Propose submit to Yes to display a key-in field,
- toggle these settings and observe the auto-generated HTML pages.
Change expert profile rights. Drag and drop profile expert into Count_Control bundle. In Count_control bundle, set expert profile access rights to read/write
Set Data logging on
- Select the temp_int bundle
- Set the Datalog Period to 65s for this bundle (setting a value activates data logging)
7. Cloud settings
The Cloud options should be left with their default values for first-time users:
These options relate to the IoTize Primer "end to end" architecture which uses dedicated space in IoTize Primer Cloud services to store:
- the configuration
- the values of the variables retrieved (data logging mechanism)
Cloud end-user features are described in Getting started 1.
Note that the architecture proposed for the Primer can be totally customized, by using the options described herebelow and by implementing the technical components of your choice (cloud services, MQTT broker/ gateways...). It is for example possible to disable theses cloud options if you don't need them.
8. Configure your Tap
- Make sure IoTize Studio is relayed to your Tap
- Click on the Configure button to send the configuration settings from IoTize Studio to your Tap (or use the menu Configuration > Write to Tap)
- Check in the output window (at the bottom of the screen) that the publishing process is OK
9. Check your changes and Publish your Web App (HTML pages)
From IoTize Studio:
- Use menu Test--> monitor (or the monitor icon) and observe the auto-generated page for the anonymous profile
- Logon as expert and observe the auto-generated page with 4 bundles, including Temp_int
- Change the LEDStatus and blinking period (variable COUNT_CONTROL)
- Note that these HTML pages are stored on the PC (not on the "cloud server")
- Stop monitoring by clicking Disconnect At this stage, the Web App is only located on your PC
Click on Publish and check in the output window that publication of the HTML file and the cloud configuration was successful.
Test the new monitoring page on your smartphone (from Tap Manager)
Tap your smartphone on your Tap, or launch Tap Manager app manually and select your Tap. Observe the auto-generated HTML page for the anonymous profile
View the variable GPIOC.ODR of Count_Status bundle, attached to an internal registry of the target application microcontroller
- Logon as expert
- View the variables
- Set the LEDStatus to 2 (to make it blink)
- Check that the "data logging" (actually data packet uploading) is running (refer to Start Data Logging.
Connect to your IoTize Primer Cloud account and observe the new configuration and Temp_int bundle graphs
Note the respective evolution of the variables temp_avg and temp: temp_avg is more stable because it is based on an average processing.
STM32 Sensor Demo application
This application is pre-programmed in the target board supplied in the evaluation kit.
The target board consists of:
STM32F103 microcontroller, with:
- built-in temperature sensor
- 32-K EPROM, pre-programmed with the Sensor Demo firmware
- TapNLink connector
- MicroUSB connector (power supply)
Main functionalities of the target firmware:
- Management of the LED, with 3 modes: on, off, auto (blinking)
- Incrementation of an internal counter
- Management of a speed variator used for counter incrementation and LED blinking
- Display of analog values: voltage and temperature
Various files are provided in the installation directory of IoTize Studio:
- The C source file and .h files (in \Examples\Sensor_STM32_DemoSensor_tem) for various derivatives
- The hex and elf files (in \Examples \Sensor_STM32_Demo\ Sensor_tem\out\ STM_32_precompiled\F1\F103...)
The SVD file for STM32F103 microcontroller (in \SVD\STM32)
The Sensor Demo application has been "IoTized"
- Your TapNLink Primer has been pre-configured at manufacturing and the package Sensor_demo app+ TapNLink Primer is ready to illustrate monitoring and Data Logging. Explained in Getting Started Part I.
- The related IoTize Studio Project Sensor_demo.iotz can be edited and modified. Explained in Getting started 2.
You can use the Sensor Demo example to:
- Program your own STM32 board, using the elf file available for other STM32 derivatives
- Compile (and potentially modify the source file) for an STM32 derivative (using the .h files) or for another Arm® Cortex®
Finally, you could implement the other demos (clock and mems) provided in the examples directory which give examples of complex objects and complex variable handling (like C structure).