Getting Started TapNLink Wireless Primer (TnL-PRIMER-NBW)
Note: If you have the TapNLink NFC-BLE Primer (ref: TnL-PRIMER-NB), refer to this Getting Started.
The TapNLink Primer for WiFi, Bluetooth and NFC (TnL-PRIMER-NBW) is factory configured to connect to mobiles over WiFi (with optional NFC pairing), as described in this Getting Started. It can be re-configured to connect to mobiles using the Bluetooth Low Energy connection (with optional NFC pairing).
Part I: End user features overview
- TapNLink Wireless Primer Kit
- To be supplied by the client:
- 5V power cable (micro USB)
- Android or iOS smartphone
To get an overview of the TapNLink Primer features, follow these steps:
- Connect the TapNLink Primer to the target board’s SWD/JTAG port.
- Power the target application.
- Activate the smartphone connections.
- Install the Sensor Demo app.
- Test on-site monitoring with NFC or WiFi.
- Test remote monitoring with MQTT.
1. Connect TapNLink Primer to the target board’s SWD/JTAG port
2. Power the 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 WIFI
- Activate NFC mode, if it's available
4. Install 'Sensor Demo App'
On an Android Device
If you own 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 'Sensor Demo' app that appears in Google Play.
You can also install the app manually from Google Play Store:
On an iOS Device
- You can install 'Sensor Demo' for iOS from Apple App Store.
- 'Sensor Demo' requires iOS 12.0 or newer. To use NFC\WiFi 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 'Sensor Demo' automatically when scanning a Tap.
5. On-site monitoring of 'Sensor Demo target application'
TapNLink Primers are pre-configured to allow both NFC and WiFi connection. If your smartphone is NFC enabled you can monitor the 'Sensor Demo target' from your smartphone using either NFC or WiFi. For iPhones, NFC is available with iOS versions ≥ iOS-13.
NFC connection: Tap your smartphone on the NFC label of TapNLink Primer to automatically launch 'Sensor Demo app'. Keep your smartphone close to the Tap so the smartphone can establish an NFC connection with the Tap.
WiFi connection: TapNLink Primers are also preconfigured as WiFi access points. You can monitor the Sensor Demo application by connecting your phone to the wireless local area network (WLAN) created by the Tap. You must use your smartphone's WIFI settings to connect to the Tap's WLAN.
Now you can launch the 'Sensor Demo app'. Choose Socket / WiFi then scan and select your sensor demo device.
TapNLink Primers are 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. Use the login menu to enter the tech credentials (login: tech, PW: tech).
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 additional R/W variables (when logged in as 'tech'): - 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
6. Remote Monitoring of 'Sensor Demo target application' via MQTT
Connecting your TapNLink Primer to your infrastucture's WIFI network automatically enables remote monitoring of the 'Sensor Demo target app' via MQTT.
You first need to switch your TapNLink Primer operating mode from Access Point to Network. For this, connect your smartphone to your TapNLink Primer. From the 'Connectivity Settings' page of the app, change the operating mode of your Tap to Network. Provide the SSID and Password necessary to connect the TapNLink Primer to your LWAN.
Select the REBOOT button to reset the TapNLink Primer.
IoTize provides its customers with an MQTT Broker at the following URL user.cloud.iotize.com to let their clients test TapNLink Primer's remote monitoring functionalities.
TapNLink Primer is pre-configured to be connected to IoTize MQTT Broker. The Tap uses its serial number and unique ID (UID) to authenticate itself to the MQTT server. Use 'Sensor Demo app' to retrieve the information you need to let the monitoring WebApp connect to the same broker ( see: Information Page ).
Using your PC browser, navigate to the WebApp version of 'Sensor Demo App' : https://sensor-demo-app-fbb73.firebaseapp.com/
Select MQTT as the means of communication. Provide the connectivity settings you previously saved from your Tap:
Select the CONNECT button to start monitoring the 'Sensor Demo target app'.
Remote monitoring is similar to on-site monitoring, the only difference is the means of communication.
Refer to Getting Started with Remote Monitoring through MQTT to learn more about remote monitoring concepts and the MQTT protocol.
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.
- Install the App Generator.
- Check the 'Sensor Demo project' configuration.
- Connect IoTize Studio to your Tap.
- Monitor the 'Sensor demo target application' from IoTize Studio.
- Generate a smartphone App.
- Add profiles, bundles and variables.
- Configure your Tap.
- Verify your configuration.
- Test your app on the smartphone.
- Connect the Sensor Demo to an IoT platform; IBM Watson or AWS.
1. Install 'IoTize Studio' (configuration software)
See IoTize Studio reference manual for details.
2. Install 'App Generator'
See Getting Started with App Generator for details.
3. Check 'Sensor Demo project' 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)
View the Target settings:
- 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 Resource View 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 MySensors 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 screen 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 to the parent profile
- in both cases, passwords are not displayed but are hashed
- 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
4. Connect IoTize Studio to your Tap
The operating mode differs depending on whether TapNLink Primer is configured as an Access Point or connected to Network. To find out which mode your Tap is in, launch 'Sensor demo', select Socket\WiFi and scan the list of available devices:
- TapNLink Primer is connected to your local WIFI Network:
You will need to write down the IP address of the Tap.
- TapNLink Primer is in Access Point mode and creates its own local WIFI Network:
Select Studio from the configuration explorer and select Socket as the 'Connection To Tap | Protocol'. Enter the IP address of the Tap in the field Socket host name\IP: - if TapNLink is in Access Point mode, use 192.168.4.1. Note that in order to start connecting to TapNLink, you should connect your PC's WIFI to the Tap's network. - if TapNLink is in WIFI, use the IP of the TapNLink in your local WIFI network as displayed in the 'Sensor Demo'.
If you had problems and did a factory reset, you must use the default values.
5. Monitor 'Sensor demo target application' from IoTize Studio
You can now monitor your target application (Sensor Demo) from IoTize Studio.
Click on Monitor.
Do some manipulations and 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 LED status. (Click the Login button and logon as user / user)
6. Generate a smartphone App
IoTize Studio integrates a custom mobile App Generator. You can take advantage of this built-in App Generator to automatically generate your own mobile app.
Use the Generate App command button to start building your mobile app.
IoTize Studio automatically generates an ionic\cordova based app when you make modifications, for example if you: - add or remove variables, - modify access rights, - change variable options such as unit, "formula", number of decimals - change page options (related to a bundle) such as page color, page name...
Use the Serve App command button to view the apps UI directly from IoTize Studio integrated browser.
Use the Monitor command button to connect IoTize Studio to TapNLink Primer, so you can interact with your 'Sensor demo target application' via IoTize Studio integrated browser.
- Click on Disconnect to stop monitoring
Please refer to the Getting Started with the App Generator to learn more about this.
7. 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 Resources View window into the Temp_int bundle. If the Resources 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)
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. Verify your configuration
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
10. Test your app on smartphone
- Set your Android smartphone to 'Developer Mode' and connect it to your PC using a USB cable.
- Open a new cmd prompt and go to c:\iotize\app_generator\sensors_demo directory where IoTize Studio has generated the 'Smartphone app'.
- Type npm run android
- 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)
- Note the respective evolution of the variables temp_avg and temp: temp_avg is more stable because it is based on an average processing.
11. Connect 'Sensor Demo target application' to an IoT Platform
STM32 Sensor Demo target 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).
Default values after factory reset
- WiFi password: ABCD1234.
- WiFi network: TAP_
- IP number: 192.168.4.1