Skip to content

TapNPass extension

This guide is for TapNPass device.

This contains functions to easily read/write data with your TapNPass device.

Warning

This extension is currently only available for typescript users

Prerequesities

Install @iotize/device-client.js

See README.md.

Install @iotize/device-ext-tapnpass.js

See README.md.

You have configured your Tap for serial communication

See Serial communication guide for more details.

Usage

Instantiate

import { TapNPass } from "@iotize/device-ext-tapnpass.js";
import { Tap } from "@iotize/device-client.js/device";

let tap: Tap;

// Init with default options
let tapnpass: TapNPass = TapNPass.fromTap(tap)

// Init with custom options
let myOptions: TapNPass.Options = {
    // this option is only used when using inflate/deflate
    // This is the duration between two inflated/deplated packet
    interframe: 200,
    // Write data chunk size 
    writeChunkSize: 230
}
let customTapnpass: TapNPass = TapNPass.fromTap(tap, myOptions)

Write data

This sample show you how to write data to write data.

import { TapNPass } from "@iotize/device-ext-tapnpass.js";

let tapnpass: TapNPass;

// Write ASCII string
await tapnpass.write("Hello World!");

// Write data
await tapnpass.write(new Uint8Array(500));

// Write with progress
let data: Uint8Array = new Uint8Array(0) ; // Your data ...
tapnpass
    .write$(data)
    .subscribe((event: TapNPass.WriteEvent) => {
        console.log(`Write ${event.chunk.length} bytes. Chunk n°${event.current}/${event.total}`)
    })

Tips

As it returns an Observable, you can benefit of rxjs power to add extra features such as retry or timeout.

Read data

This sample show you how to read data.

import { TapNPass } from "@iotize/device-ext-tapnpass.js";
import { Lenght, NoMoreData } from "@iotize/device-ext-tapnpass.js/operators";

let tapnpass: TapNPass;
let data: Uint8Array;

// Read the whole buffer
data = await tapnpass.read();
data = await tapnpass.read(NoMoreData);

// Read 34 bytes
data = await tapnpass.read(Lenght(34));

// Read until custom condition is met
let myCondition: TapNPass.ReadStopCondition = (chunk: Uint8Array, total: number) => {
    return true;
}
data = await tapnpass.read(myCondition);

// Read with compression data
data = await tapnpass.read(NoMoreData, {
    inflate: true
});

// Read with progress
tapnpass .read$(NoMoreData)
    .subscribe((event: TapNPass.ReadEvent) => {
        if (event.chunk){
            console.log(`New chunk read: ${event.chunk.length} bytes`)
        }
        if (event.result){
            console.log(`Read complete! Received ${event.result.length} bytes`)
        }
    })

Limitation

Your TapNPass buffer has a maximum capacity of 28KB by default. It will miss data when there are more than 28KB of data sent. See Changing reception/transmission maximum buffer size

Advance options

Changing reception/transmission maximum buffer size

By default, reception and transmission buffer size are both 26KB (for a total of 56KBo data) but it can be changed with the API

import { TapNPass } from "@iotize/device-ext-tapnpass.js";
let tapnpass: TapNPass;

// Set transmission size to 34KB
await tapnpass.setTransmissionBufferSize(34);

import { TapNPass } from "@iotize/device-ext-tapnpass.js";
let tapnpass: TapNPass;

// Set reception buffer size to 43 KB
let receptionBufferSize = 43
await tapnpass.setTransmissionBufferSize(56-receptionBufferSize);

Warning

Increasing transmission buffer size will reduce the reception buffer size (or vice versa)

  • If you use compression feature, maximum transmission buffer size is 41KB
  • Otherwise it's 55KB

Reading Tapnpass stats

You can read various Tapnpass information using service tap.service.adp.getStatus().

import { TapNPass } from "@iotize/device-ext-tapnpass.js";
import { Tap } from "@iotize/device-client.js/device";

let tap: Tap; // ...

let adpStatus = (await tap.service.adp.getAdpStatus()).body();

// Display tapnpass version
console.log('Tapnpass version: ', JSON.stringify(adpStatus.header.version))

// Show USB state
console.log('USB: ', adpStatus.state.usbDisconnected ? 'DISCONNECTED' : 'CONNECTED');

Full example

Below a full example of an app that will send "Hello World!" message and display the response.

import { TapNPass } from "@iotize/device-ext-tapnpass.js";
import { Tap } from "@iotize/device-client.js/device";
import { UartSettings } from "@iotize/device-client.js/device/model";
import { FormatHelper } from "@iotize/device-client.js/core/format/format-helper";

let tap: Tap; // ... 

// Connect to the Tap
await tap.connect();

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,
    slv: 0,
    ofs: false
};

// Configure uart
(await tap.service.target.setUARTSettings(uartSettings)).successful();


// Ask Tap to connect to the target application
(await tap.service.target.connect()).successful();

// You may need to login (according to the configuration)
// tap.login("username", "password")

// Init TapNPass instance
let tapnpass = TapNPass.fromTap(tap);

// Write message
await tapnpass.write("Hello World!");

// Read response
let response = await tapnpass.read((chunk, total) => total > 0);

console.info('Received response: ' + FormatHelper.toAsciiString(response))

Troubleshooting

Error UNAUTHORIZED

With the default configuration, serial port is protected. Only admin used can read/write data. Simply authenticate before using these features with tap.login("username", "password")

You can also change the configuration with IoTize Studio.

Errors starting with TARGET_PROTOCOL...

This error may occured in different cases. Here a list of possible reasons:

  1. You did not call tap.service.target.connect() before reading/writing data
  2. Your target device serial configuration is not the same as the one configured in your Tap device
  3. Your TapNPass is not properly configured to perform serial communication