Skip to content

IoTize Toolbox

Summary

This goal of this app consists in demonstrating serial communication with either TapNPass or TapNLink:

  • A ‘terminal’ utility allows to send/receive characters.
  • A ‘modbus’ utility allows to drive one or several Modbus (slave) devices. Only Modbus-RTU is supported.

Both utilities can be used on any available serial port (RS232, RS485 or USB with TapNPass and UART with TapNLink). This app is also a good starting point to start serial communication and it features a software ‘baud rate detection’. It is also a complete example to understand how to interface your own app with the TapNLink API for Cordova.

Availability

Apps:

Source files:

https://github.com/iotize-sas/toolbox

TapNPass embeds a TapNLink module. Whatever your context (if you are using a TapNPass or a simple TapNLink module), you must be logged in as an authorized user with corresponding rights for accessing the different features demonstrated within this app. For TapNPass, the initial configuration is fine to access all the features without any specific login (“anonymous” login is sufficient). But for TapNLink, you need to create this configuration by using “IoTize Studio”. Please look at the IoTize Documentation center doing this task. You can also use the configuration file (.iotz) located in the “\IoTize\IoTize Studio\Examples\Toolbox” folder.

More specifically, you need to be authorized for the following ‘advanced features’:

  • Serial (for using Terminal)
  • Modbus Direct
  • TapNPass Control (if you are using a TapNPass device)

Note that the easiest way is to associate “anonymous” to these features within a unique bundle. But you can also create a dedicated profile (in this case you will need to login before any action). You can associate the ‘Toolbox’ package as default app (Android AAR), but this is not mandatory (the purpose of this association is only to launch automatically the App when taping the NFC interface).

Launching the Toolbox app

After installing the Toolbox App, launch it either with NFC or directly from the list of apps on your mobile. You will get the splash screen followed by the ‘Scan’ screen.

home

Click on the ‘Start Scan’ button and the list of available BLE devices will be searched. You also may swipe down in the app to launch the BLE scan and/or refresh the list of available devices.

Tap the name of your device to select it, then tap the ‘home’ sign, or swipe right from the left side to reach the main menu:

menu

There, you may navigate through the app, see the currently logged user and login / logout.

NFC to BLE

If you launched the app with NFC or tap a device while not connected, the application will retrieve informations from the tap through NFC in order to connect with BLE.

Settings

settings

When the page is displayed, if no settings are displayed, click on ‘Read from the Tap’ to refresh the current contents. Then assign the different parameters and record the new settings by clicking on ‘Apply Settings’. The different options allow to configure the classic UART settings. The ‘physical port’ depends on your device: for a simple TapNLink, only the ‘UART direct’ is available. For TapNPass, you can choose among RS232, RS485 and USB (to connect a FTDI, Silabs or CDC USB device).

If you want to work with modbus but do not know baudrate and/or bit parity to use, you may use the "Autobaud" feature to find the right baudrate / bit parity combo for your actual use. Be sure to configure the right physical port before scanning for baudrate

These settings are used through the whole application. You may need to login with an authorized user to read and/or write these settings, depending on the Tap configuration

Modbus utility

Main Page contents

The main page for the Modbus utility presents different areas:

modbus
Area Description
Register display area It contains the list of registers you wish to monitor.
Register definition When a register is selected, it contains the data (address, slave, size, type,…) defining the register.
Input field To enter the value to be written (only for ‘write register’ command).
Command button You can either read or write the contents of a register.

Modbus register definition

If you click on the “register area” or on the settings icon at the top-right hand corner, the page below is displayed:

modbus

This page allows to define the current register to be read/written:

  • The slave id (8 bit value),
  • The register address (16 bit value)
  • The modbus type of the register (default is ‘holding register’),
  • The format: Modbus registers are 16 bit long, but they will be truncated for 8 bit values, and two consecutive registers will be assigned for 32 bit values.
  • The length: the number of consecutive registers to be accessed,
  • The display mode for the retrieved value: either hexadecimal or decimal.
  • The display mode of the register: either hexadecimal or decimal (this also affects the way you enter the register address).

If you click “Save” then “Read”, you will get the following screen:

modbus

Where the holding register at the address 0x130 of the slave 1 is read as a 32 bit value.

You can now decide to keep this register in the Modbus page by swiping left its line. The ‘save’ button appears and, when clicked, the register line is stored. You can store multiple lines this way, preventing you to constantly edit the modbus settings.

Swiping one "Saved Request" line allows you to refresh the current value,start/stop a monitoring (left side), edit the request settings or delete the line (right side)

modbus-save modbus-left-options modbus-right-options

Request Settings allow to modify

  • The value's display mode (as Hex Value, ASCII, float, ...)
  • The order of Bytes (32 bits values only)
  • The monitoring period (in milliseconds)

These settings only affect the current request. Therefore, you can store multiple requests, each one with its own display mode and monitoring state.

modbus-save modbus-left-options

Troubleshooting

If you are not able to display any value of your Modbus slave, check the following possibilities:

  • Double check the UART settings… This is the most frequent cause.
  • Check the slave address of your device.
  • Check that you are granted to use the ‘modbus features’ in the current configuration. For a brand new TapNPass, the initial configuration allows an ‘anonymous’ login to use either Modbus or the Serial communication. You can also try to log as admin (password ‘admin’), on the sidemenu:

modbus-login

Terminal Utility

The terminal utility is a simple terminal that allow to send a command or to display the stream of received characters. you can navigate to the “Terminal” utility through the sidemenu.

You can now select the Terminal utility and see its main page:

terminal

The Terminal page offers few buttons:

  • At the upper right corner, the settings button allows to specify the input/display parameters.
    • Data format: read and write as hexadecimal bytes, or using ASCII
    • End of line: defines which character you want at the end of your ASCII input (disabled if data format is set to HEX). Possible values are CR, LF, both or none
    • Reading task, which displays the current state of the terminal continuous reading routine
  • At the upper left corner, besides the menu button, you can clear the terminal view (care as it deletes the prior messages)
  • At the bottom, there is the “Data Input” field and the send button.
terminal-settings terminal-read

To use the Terminal, click on the “Data Input” field to enter the command you want to send. Both the command and the received answer will be displayed

Infos

This page shows some informations about the Tap and its target (see below)

infos