IoTize Toolbox
Summary
This goal of this app is to demonstrate 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 (RS-232, RS-485 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.
Apps:
Source files:
https://github.com/iotize-sas/toolbox
TapNLink configuration
TapNPass has an embedded TapNLink module. Whether you are using a TapNPass or a simple TapNLink module, you must be logged in as an authorized user with corresponding rights to access the various 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 to do 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 to be authorized is to associate “anonymous” to these features within a unique bundle. Alternatively you could create a dedicated profile (in this case you will need to login before any action). You can associate the ‘Toolbox’ package as the default app (Android AAR) so that the App launches automatically when the NFC interface is tapped, but this is not mandatory.
Launch Toolbox
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.
Click on the Start Scan button to search for available BLE devices. 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:
There, you may navigate through the app, see the current user and login / logout.
NFC to BLE
If you launched the app with NFC or tapped a device while not connected, the application retrieves information from the Tap via NFC in order to connect with BLE.
Settings
If the settings page is empty, click on Read from Tap to refresh the current contents. Change the parameters as required and save them by clicking on Apply Settings. These options configure the classic UART settings. The Physical port depends on your device; for a simple TapNLink only UART direct is available; for TapNPass you can choose among Auto, None, RS-232, RS-485 and USB (to connect a FTDI, Silabs or CDC USB device).
If you want to work with modbus but do not know what baudrate or bit parity to use, 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
Main Page
The main page for the Modbus utility presents several areas:
| Area | Description |
|---|---|
| Register area | 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 read or write (send) the contents of a register. |
Settings: 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:
This page allows to define the current register to be read/written:
- Slave id (8-bit value),
- Register address (16-bit value)
- Modbus type of the register (default is ‘holding register’),
- Format: Modbus registers are 16 bits long, but they will be truncated for 8-bit values, and two consecutive registers will be assigned for 32-bit values.
- Length: the number of consecutive registers to be accessed,
- Display mode for the retrieved value: either hexadecimal or decimal.
- 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:
Where the holding register at address 0x130 of 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 from constantly editing 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).
Request Settings allow to modify:
- The value's display mode (Hex, ASCII, float, ...)
- The order of bytes (32-bit 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.
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 authorized 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 Serial communication. You can also try to log as admin (password ‘admin’) on the sidemenu:
Terminal
The Terminal utility is a simple terminal that sends a command or displays the stream of received characters.
The Terminal page offers few buttons:
- In the upper-right corner, the settings button specifies 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.
- In the upper-left corner, beside the menu button, you can clear the terminal view (take care as it deletes prior messages).
- In the bottom, there is the “Data Input” field and the send button.
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 information about the Tap and its target (see below)
