Skip to content

Serial communication with the target application

This guide details how communicate with a target application using serial protocols.

The TapNPass device communicates with RF technology (BLE, Wi-Fi, NFC) via the API. The TapNPass device forwards data to the Target Application using the correctly configured protocol (RS-232, RS-485, USB, ...).

General architecture

Prerequisities

What you need

  • TapNPass
  • Target Application that handles serial communications
  • Mobile Device with RF capabilities
  • IoTize Studio

Configure your Tap Device

Your Tap must be configured as a TapNPass type of target. To do this, in IoTize Studio (manual) configuration explorer, set option IoTized Application / Target / Type of Target to System (TapNPass).

Choose the default target protocol to use with option IoTized Application / Target / Link target <=> tap / Target Protocol:

  • Modbus
  • Serial standard
  • Serial transparant

[Optional] You can configure serial settings in IoTized Application / Target / Link target <=> tap / Serial Configuration, but these values can also be programmed.

Do not forget to Apply the configuration.

You are able to connect to your Tap Device

If you don't know how to connect to your Tap Device, read Getting Started.

import { TargetService } from '@iotize/device-client.js/device/impl/service/target-service'
import { IoTizeDevice } from '@iotize/device-client.js/device'

let tap: Tap = // ...;
let targetService: TargetService = tap.service.target; 
IoTizeDevice device = IoTizeDevice.fromProtocol(
    yourComProtocol
);
device.connect();
TargetService targetService = device.service.target;
let tap: IoTizeDevice = // ...
let targetService = tap.service.target

The next examples use the TargetService instance to regroup functionalities and communicate with the target application.

[Optional] Check device configuration programmatically

You can check device configuration programatically with @reference:TargetService::getProtocol()

let protocol = (await targetService.getProtocol()).body();
console.log(`Target prototocol is ${protocol}`);
TargetProtocol protocol = targetService.getProtocol().get();
Log.i(TAG, "Target protocol is " + protocol.toString());
let targetProtocol: TargetProtocol = targetService.getProtocol().body()
print("Target protocol is \(targetProtocol)");

Target protocol value should be either Modbus, serial standard or serial transparent.

If not, you incorrectly configured your Tap Device with IoTize Studio or programmatically.

Serial configuration

Read serial configuration

To read the serial configuration, use @reference:TargetService::getUARTSettings().

let settings: UARTSettings = ((await) targetService.getUARTSettings()).body();
UARTSettings uartSettings = targetService.getUARTSettings().get();
let uartSettings: UartSettings = targetService.getUARTSettings().body()

This will give you a UartSettings.

Edit serial configuration

To edit serial configuration:

import { Tap } from "@iotize/device-client.js/device"
import { UartSettings } from "@iotize/device-client.js/device/model";

let tap: Tap; // ... initialized tap 

// Create your UART configuration
let uartSettings: UartSettings = {
    baudRate: 9600,
    physicalPort: UartSettings.PhysicalPort.RS485,
    stopBit: UartSettings.StopBit.ONE_AND_HALF,
    bitParity: UartSettings.BitParity.EVEN,
    dataBitsLength: UartSettings.DataBitsLength._8,
    handshakeDelimiter: UartSettings.HandshakeDelimiter.CR_LF,
    handshakeValue: UartSettings.Handshake.RTS_CTS,
    timeout: 255,

    // Modbus specific options 
    slv: 0,
    ofs: false
};

// set the configuration on the device (dynamically)
(await tap.service.target.setUARTSettings(uartSettings)).successful()
// OR write the configuration (permanantly). These new uart settings will be kept event after tap reboot
(await tap.service.target.writeUARTSettings(uartSettings)).successful()

// To apply the new configuration, reconnect to the target
(await tap.service.target.connect()).successful();

// Create your UART configuration
UARTSettings uartSettings = new UartSettings();
uartSettings
    .setBaudRate(9600)
    .setBitParity(UartSettings.BitParityEnum.NONE)
    .setDataBitsLength(8)
    .setTimeout(200)
    .setStopBit(UartSettings.StopBitEnum.ONE)
    .setHandshake(UartSettings.HandshakeEnum.CTS)
    .setHandshakeDelimiter(UartSettings.HandshakeDelimiterEnum.NONE)
    .setPhysicalPort(UartSettings.PhysicalPortEnum.USB)
    ;
// write the configuration on the device 
targetService.setUARTSettings(uartSettings).execute();

// To apply the new configuration, reconnect to the target
Response<Void> response = targetService.connect().execute();
if (!response.isSuccessful()){
    throw new DeviceResponseError(response);
}
let uartSettings: UartSettings = UartSettings(
    physicalPort: .USB,
    stopBit: .ONE,
    parity: .NONE,
    dataLength: 8,
    baudRate: 9600,
    handshakeDelimiter: .NONE,
    handshakeValue: .CTS,
    slv: 0,
    ofs: false,
    baudrate: 9600
)
// write the configuration on the device 
try targetService.setUARTSettings(uartSettings).successful();

// To apply the new configuration, reconnect to the target
try targetService.connect().successful();

Note:

  • When you reset the tap, the configuration will be lost
  • Configuration will not be applied until you call targetService.connect()
  • For more information about these parameters see this link

If you want to write only a subset of the configuration, read the configuration first and update the value.

import { Tap } from "@iotize/device-client.js/device"
import { UartSettings } from "@iotize/device-client.js/device/model";

let tap: Tap; // ... initialized tap 

// Read current config first
let uartSettings: UartSettings = (await tap.service.target.getUARTSettings()).body();

// Change only a subset of options
uartSettings.baudRate = 187500;

// Write the new configuration 
(await tap.service.target.setUARTSettings(uartSettings)).successful()
// Apply new configuration
(await tap.service.target.connect()).successful()

// Read config first
UartSettings uartSettings = device.service.target.getUARTSettings().execute().body();

// Change only a subset of options
uartSettings.setBaudRate(187500);

// Write the new configuration
Response lastResponse;
lastResponse = targetService.setUARTSettings(uartSettings).execute();
if (!lastResponse.isSuccessful()){
    throw new DeviceResponseError(lastResponse);
}
lastResponse = targetService.connect().execute();
if (!lastResponse.isSuccessful()){
    throw new DeviceResponseError(lastResponse);
}
// Read config first
let uartSettings = try device.service.target.getUARTSettings().body();

// Change only a subset of options
uartSettings.baudrate = 187500;

// Write the new configuration
try device.service.target.setUARTSettings(value: uartSettings);
try device.service.target.connect();

Serial communication

Send data to target

try{
    // Send "Hello World" and wait for a response
    let response1: Response<Uint8Array> = (await) targetService.sendReceive("Hello World".getBytes());
    let targetResponse: Uint8Array = response1.body();
    console.log(`Target application responded: `, targetResponse);

    // Send "Hello World" and do not wait for a response
    let response2: Response<Uint8Array> = (await) targetService.send("Hello World".getBytes());
    if (!response2.isSuccessful()){
        throw new DeviceResponseError(response2);
    }
    console.log(`Successful send `);
}
catch (err) {
    console.error(`Response error: ${err}`);
}
// Send "Hello World" and wait for a response
Response<byte[]> response1 = targetService
        .sendReceive("Hello World".getBytes())
        .execute();
if (response1.isSuccessful()){
    byte[] data = response1.body();
}

// Send "Hello World" and do not wait for a response
Response<Void> response3 = targetService
        .send("Hello World".getBytes())
        .execute();
if (response3.isSuccessful()){
    // OK
}
// Send "Hello World" and do not wait for a response
targetService.send("Hello World".bytes).successful()

Read target data

try{
    // Send "Hello World" and wait for a response
    let response1: Response<Uint8Array> = (await) targetService.read();
    let targetResponse: Uint8Array = response1.body();
    console.log(`Target application responded: `, targetResponse);
}
catch (err) {
    console.error(`Response error: ${err}`);
}
// Read data
Response<byte[]> response2 = targetService
        .read()
        .execute();
if (response2.isSuccessful()){
    byte[] data = response2.body();
}
// Read data
targetService.read().successful()