Target variable¶
Target variable is a powerful feature of your Tap Device. You can easily expose variables from your target application and use the API to read, write and monitor them.
Prerequisities¶
What you need¶
- Tap Device
- IoTize Studio
- Target Application that handles serial communications
- Mobile Device with RF capabilities
You have iotized your target application variables¶
See steps to iotize your target application.
Configure your device object to work with variables¶
When you iotize your target application, IoTize Studio gives a unique identifier to your variables which it uses to access the corresponding resource in your Tap Device.
Tips The variable identifier
is found in IoTize Studio: IoTize Explorer / Bundles / <Your bundle> / <Your variable> / Variable Information / Id
.
Manually¶
// Instantiate a device let device = IoTizeDevice.create(); // Configure your variables device .variables .add("temperature", { id: 1, // The variable identifier converter: NumberConverter.uint32instance() }) .add("voltage", { id: 2, converter: NumberConverter.uint32instance() }) .add("LEDStatus", { id: 3, converter: new UniqMaskConverter({ 0x0: 'OFF', 0x1: 'ON', 0x2: 'AUTO' }) }); // You can also configure bundles device .bundles .add("Sensors", { id: 1, // Variables must be defined (see above) otherwise an error will occur variables: ["temperature", "voltage"] });
IoTizeDevice device = ...; // Configure your variables device .getTargetVariables() .add(VariableConfig.FLOAT(1, "Voltage_V")) .add(VariableConfig.UINT(4, "Count")) // ... ; // You can also configure bundles BundleManager bundleManager = device.getTargetBundles(); bundleManager.add(new Bundle( 1, // Bundle ID "Sensors", // Bundle name 61, // Datalogging period Arrays.asList( VariableConfig.FLOAT(1, "Voltage_V"), // First variable in bundle VariableConfig.FLOAT(2, "Temperature_C") // Second variable in bundle ) )); bundleManager.add(new Bundle( 1, "Count_Status", 61, Arrays.asList( VariableConfig.UINT(4, "Count"), VariableConfig.ENUM(7, LEDStatusEnum.class, "LEDStatus") ) ));
With a TapConfigurator instance¶
You can use TapConfigurator to configure your Tap device.
Configure from an IoTize Studio configuration file¶
import { IotizeConfigFactory } from "@iotize/device-config.js/iotize-config-factory"; import { TapConfigConfigurator } from "@iotize/device-extras.js/configurator/tap-config-configurator"; import { IotizeConfigModel } from "@iotize/device-config.js/model/iotize-config-model"; // Get the content of the configuration file <serialnumber>.cloud generated by IoTize Studio // If you are in node.js environment you can use fs.readFileSync // Otherwise you may need to perform an http request or add a configuration file directly into your app. let yourConfigFileContent: string = "<?xml version="1.0"?><IOTizeConfiguration Version="1.2.0" Lock="8"> ..."; // Parse the config into an IoTizeConfigModel let configModel: IoTizeConfigModel = IoTizeConfigFactory.fromXML(yourConfigFileContent); // Create the TapConfigConfigurator instance with this model. let tapConfigConfigurator = new TapConfigConfigurator(configModel); // Apply the configuration to your device object await device.configure(configurator);
// Not documented yet
Read/Write values¶
Read value¶
When you read a configuration variable value, this sends a request to the Tap and decodes the output value with the converter you provided during the configuration.
// Get variable object by name let variable: Variable<number> = device.variables.get("Temperature_C"); let value = await variable.read();
VariableInteraction<Float> variable = device.getTargetVariables().get("Temperature_C"); Float value = variable.read();
Write value¶
let value = await variable.write(123);
VariableInteraction<Float> variable = device.getTargetVariables().get("Temperature_C"); variable.write(12.3);
Monitoring¶
Once the variable object is configured, you can easily monitor the values.
Access the monitor object with function Variable::monitor()
to get a handle on a VariableMonitor
implementation.
You have 3 main functions:
start()
to start value acquisitionpause()
to pause value acquisitionstop()
to stop value acquisition and cleanup allocated resources.
Note: Values are acquired by polling
Start monitoring¶
For a variable¶
let variable: Variable<number> = device.variables.get("temperature_C"); let variableMonitor = variable.monitor(); variableMonitor .start({ forceRefresh: true, // Update callback is called even if variable has not been modified delay: 1000, // Checks variable updates every 1000 milliseconds duration: -1, // Runs until Monitor::stop() has been called // TODO add options old/cold }) .values() .subscribe({ next: (value: number) => { // Is emitted every 1000 milliseconds console.log(`New value: ${value}`); } }); // Listen to monitoring events variableMonitor .events() .subscribe((event) => { console.log(`Event: `, event); });
VariableInteraction<Float> variable = device.getTargetVariables().get("Temperature_C"); MonitorEngine<Float> variableMonitor = variable.getMonitor(); variableMonitor.start(); variableMonitor .values() .subscribe( (Float value) => { // Is emitted every 1000 milliseconds Log.i(TAG, "NEW VALUE => " + value); } );
Important: If you want to change the monitoring parameters such as monitoring frequency, you must stop monitoring and then restart with your new parameters.
For a bundle¶
You can monitor an entire bundle which is faster than monitoring each variable one by one.
let bundle: Bundle = device.bundles.get("<YourBundleId>"); let bundleMonitor = bundle.monitor(); bundleMonitor .start({ forceRefresh: true, // Update callback is called even if variable has not been modified delay: 1000, // Checks variable updates every 1000 milliseconds duration: -1, // Runs until Monitor::stop() has been called // TODO add options old/cold }) .values() .subscribe({ next: (value: number) => { // Is emitted every 1000 milliseconds console.log(`New value: `); } }); // Listening to monitoring events bundleMonitor .events() .subscribe(() => { });
// Not documented yet
Pause/Stop monitoring¶
// You can stop or pause monitoring whenever you want. // Method 1: Pause monitor monitor.pause(); // ... // When paused you can easily restart it monitor.start(); // Method 2: Stop monitor // The main difference with Pause is that observable values stream will be complete when Stop is used. // You have to resubscribe to a new observable value stream to restart monitoring. monitor.stop();
// You can stop or pause monitoring whenever you want. // Method 1: Pause monitor monitor.pause(); // ... // When paused you can easily restart it monitor.start(); // Method 2: Stop monitor // The main difference with Pause is that observable values stream will be complete when Stop is used. // You have to resubscribe to a new observable value stream to restart monitoring. monitor.stop();