Skip to content

Getting Started With TapNPass

Reminder

The TapNPass provides radio access via a mobile device to monitor/modify existing electronic systems though a serial connector, thus removing the need for cables.

It adapts easily to existing systems that were not designed for wireless communication. TapNPass has an embedded TapNLink module which can easily be configured in IoTize Studio to convert your mobile device into a powerful Human Machine Interface for your system.

Content of this document

This documentation describes 2 quick 'step by step' examples for both communication modes, Serial and Modbus. These examples can be run without detailed knowledge of:

Scope of the examples

The examples apply to both the Fix and Nomad versions of TapNPass.


'Serial Standard' sample

The TapNPass you received is pre-configured to work in 'Serial Standard' mode. In this example we are going to re-configure TapNPass to perform an 'Echo test' using IoTize Terminal mobile app.

1. Required equipment

  • TapNPass
  • RS-232 cable
  • An NFC enabled Android smartphone with Android version 6.0 or later (the demo can work only with BLE, but it is more secure to pair automatically using NFC)
  • A Windows based Personal Computer
  • IoTize Studio configuration software, installation procedure available here
  • Tap Manager
    • Tap Manager is used as a relay to connect IoTize Studio to TapNPass (to transfer the configuration)
    • Install Tap Manager from Google Play Store

  • IoTize Terminal app

    • Your TapNPass is pre-configured with IoTize Terminal app (the NFC tag contains its AAR)
    • This simple app transmits strings to your target system and displays the answer.
    • Install IoTize Terminal on your mobile device:
      • If your mobile device is NFC-enabled, tap it on your TapNPass to automatically retrieve the app
      • Otherwise, install IoTize Terminal from Google Play Store

2. Connect cable to TapNPass

  • Connect RS-232 cable to TapNPass.

    TapNPass connected with RS232

  • Shortcut RXD and TXD pins of the RS-232 connector using, for example, a simple jumper (pins 2 and 3 on the DB9 connector).

    TapNPass connected with RS232

3. Open IoTize Studio

IoTize Studio configuration software has a few sample projects in the Examples subdirectory. This tutorial uses the Terminal project ( '...\Examples\Terminal\terminal.iotz' ).

  • Open this project using File|Open from the main menu of IoTize Studio.
  • Open IoTized Application|Target from IOTZ Explorer.
  • Some of these settings can be modified dynamically from the Terminal App or by developing your own native app and using the related APIs.
  • In this tutorial, we change the project's configuration to setup an Echo test.

4. Configure Access Control

The 'Terminal' project is already configured, this step just explains what we've done.

TapNPass provides several access control notions to assign permissions to users. To enable the use of IoTize Terminal App without any login/password, TapNPass must be configured to grant Serial Access Rights to the Anonymous profile (by default, serial port access is only authorized to the Admin profile).

Note there is only one Bundle in this configuration, named 'Serial Access Rights' which is attached to:

  • the Protected Feature 'Serial' (accessible from the resource view)
  • the Profile 'anonymous' (see underlying principes).

Features Settings

5. Configure Communication

In the IOTZ explorer pane (on the top left) expand the menu IoTize Application, select the menu Target and view the various fields underneath:

  • Type of Target: set to 'System (TapNPass)'.

    • IoTize Studio can manage different types of Tap.
  • Target protocol: set to 'Serial Standard'.

    • Serial Standard corresponds to communication where data streams are exchanged without any modification nor decoding
  • Serial Port: set to 'RS-232' as we are going to use the RS-232 cable for this test.

    • TapNPass features 3 hardware ports: RS-232, RS-485 and USB.
    • If you select 'AUTO':
      • The USB port is selected if a USB device is detected.
      • Otherwise, RS-232 is selected.
  • Serial configuration: set Handshake to 'None'.

    • In the case of the Echo demo, we don't care about the values of these settings (Baudrate, Parity, Stop bits, Length, Handshaking method) (just keep 'none' for handshake)
    • The IoTize Terminal App is both the emitter and the receiver (it simulates the target system)

    Target Settings

6. Setup relay

  • Follow these instructions to set up a relay between your TapNPass and IoTize Studio, using Tap Manager App.

7. Transfer config to TapNPass

  • Launch Configuration|Write to Tap from the main menu of IoTize Studio.
    • The configuration will be transferred and copied into TapNPass.
    • Check IoTize Studio Output View'* to see the successful termination of the configuration process.

8. Run an 'Echo test'

You are now ready to test the 'Echo' from the IoTize Terminal App.

Tap your mobile device to automatically launch IoTize Terminal App. This app sends a character string from your mobile device to your (simulated) target system through TapNPass, and displays the response.

  • Type characters in the input box of IoTize Terminal App.
  • These characters appear in the display screen and are 'echoed' again as a response (the are sent through TXD pin and 'echoed' back through the RXD pin, and then sent back to your mobile device).

Target Settings


'Modbus' sample

Modbus can access 'variables' through the access control mechanism. This is an efficient way to use TapNPass when the target equipment supports Modbus.

1. Required equipment

  • TapNPass
  • A Modbus slave-device running in RTU mode (at the moment, TapNPass/TapNLink do not support ASCII mode).
  • A cable to connect TapNPass to your Modbus slave device.
  • An Android mobile device, with Android version 6.0 or later, with BLE and NFC connections enabled (the demo can work just using BLE, but it is more secure to use NFC for pairing)
  • A Windows based computer with IoTize Studio configuration software, installation procedure available here
  • IoTize Tap Manager App
    • This app is used:
      • as a relay to connect IoTize Studio to TapNPass (for the configuration process),
      • to run the Web monitoring app (static site), from its internal 'viewer'
    • Install Tap Manager from Google Play Store.

2. Connect cable to TapNPass

  • Connect the matching cable between TapNPass and your slave device.

    • RS-485 is the most popular hardware protocol for Modbus, but it could be also RS-232 (check with the documentation of your device).
    • The supplied cables comply with the DB9 connectors described in the modbus.org specification, but various connectors with various pinout could also be used.
    • If your system does not comply with the supplied cables, you must to build your own adapter.
    • If needed, further information can be found in TapNPass Reference Manual.
  • If you are not in a 'bus context' (multiple device chain), but with a single RTU device, it is better to set the embedded 120 ohm termination resistor.

3. Create project

Launch IoTize Studio and create a new project using File|New which opens a Wizard from which you can enter:

  • The Name of your project (for example 'test_modbus')
  • The Location (folder) of the configuration file
  • The Tap model: in this test_modbus demo, select 'TapNPass', which refines the choice of options in the various menus.

Target Settings

Once the 3 fields above are completed, push the Create button. You can then specify your configuration in more detail. In the top left pane titled IOTZ Explorer, we will setup the 3 first groups of settings: Target, Tap and Mobile App.

4. Set up Target options

Expand IOTZ Explorer (on the top left), select Target sub menu and view the Target details window underneath the Explorer window.
The preset values depend on the previously opened project. You can overwrite and customize them to your target system:

Target Settings

  • Serial Port: set this option as your target serial protocol (generally RS-485 for ModBus).

  • General Settings for communication: Baudrate, Parity, Stop bits, Length, Handshaking method must be defined in accordance with your target system.

  • The SVD/XML option is not relevant for TapNPass in this version (future versions will define an XML file containing the address and structure of 'ModBus registers').

  • You can ignore Identification with LEDs and Enable LEDs settings.

5. Configure Tap

Keep the default values for this sub-section (mainly security parameters).

6. Configure Mobile App

  • Expand the IoTized application menu, in IOTZ explorer.
  • Click on the Mobile app submenu
  • Set the option App to 'IoTize Tap Manager app' to use the built-in Web App generator.
  • Location of the Web app (also referred to as Static Website):
    • we advise you to keep the default ('Primers Development server') which is an IoTize server (for provisioned taps only)
    • this allows you to use the 'Publish' function to deploy your WebApp from IoTize Studio to the final location

Target Settings

7. Create a variable

We can edit the complete list of available registers, but for this first test, we create a single registers-symbol manually:

  • In the Resource pane, select Custom Symbols (left click), then open the pop-up menu (right click). You can now create a New Absolute Symbol that will be named 'VarAbs_0' by default.

Target Settings

  • Select this new symbol and enter the values for your specific symbol (you need to know the address and the characteristics of one Modbus register of your system):

    • Name: rename it (for example) as 'TestReg'.
    • Address: 16-bit value in Modbus register map of the device (specific to your modbus system).
    • Slave address: if several devices are chained, enter the address of your target device (specific to your modbus system). If you keep 0, the default slave address (defined in the Target configuration) will be used.
    • Unit Size the size of the register (8, 16 or 32 bit).
    • Quantity if the symbol is part of an array.
  • You can now drag the created symbol and drop it into the Main Bundle (in this tutorial there is only one Bundle, called Main).

  • If you want to attach other ModBus registers to this bundle, you can repeat the sequence above.

Target Settings

You can see on the screenshot above that the anonymous profile has been linked by default to the Main bundle:

  • Everybody can access this variable (ModBus register) without login/password.
  • This is fine for a first step, but if you need to restrict access, refer to the Access control mechanisms for further details.
  • After this first test, you could also try to create a custom profile ('Maintenance' for example) requiring authentification.

You can view the HTML page automatically generated for this combination bundle/profile Main/ anonymous by clicking on the anonymous profile in the main bundle.

In RED the generated HTML

8. Publish the web app (HTML files)

Click on the Publish button (in the upper tool bar)

Publishing the generated HTML

Important notes:

  • The Publish feature is available only if your TapNPass has been provisioned by IoTize in our cloud platforms.
  • You need an Internet Access on your PC and you must authorize (in your firewall) IoTize Studio to push out the HTML files.
  • If your TapNPass has not been provisioned, you must copy these pages (using your own ftp utility) onto your server. In this case, use the menu to define the HTML pages location (complete path) so that Tap Manager can retrieve them.

9. Setup relay and configure your TapNPass

  • Follow these instructions to set up a relay between your TapNPass and IoTize Studio, using Tap Manager App.
  • Launch Configuration|Write to Tap command from the main menu of IoTize Studio..
  • Check in IoTize Studio Output View the successful termination of the configuration process.

10. Test your sample Web app from IoTize Studio

  • Click on the Monitor button (in the upper menu bar or from the menu Test/Monitor)
  • This allows you to view your web app in IoTize Studio, using the built-in Web App generator

11. Run the ModBus Web App on your mobile device

  • Tap your mobile device on your TapNPass to launch Tap Manager App (which retrieves and runs the Web app we have just published).
  • Alternatively, you can launch manually Tap Manager App, then select the BLE device corresponding to your TapNPass.

12. Customize your web app (optional)

If needed, customize the HTML page, using web technologies (css, HTML...) for example to take into account your graphical charter.
You can store the modified HTML page(s) in another directory on your PC. You must update the fields Home Page and Website Path for monitoring accordingly (from the main menu Studio, accessible on the top left).