Quick start¶
Install¶
Install the library according to your language/platform
Instantiate an IoTizeDevice object¶
Configure the communication protocol to use¶
IoTize devices support multiple communication protocols (See communication protocols user guide for more information).
Note for Javascript users Each communication protocol are separated into a specific package. You can see the list on npmjs.org
Here are somme example of communication protocol you can use:
// For bluetooth low energy communication from a mac address ComProtocol protocol = BLEProtocol.fromAddress(context, "AA:BB:CC:DD:EE")// ... // For bluetooth WIFI communication ComProtocol protocol = WIFIProtocol.fromIP(context, "192.168.1.50")// ... // For NFC communication android.nfc.tag myNfcTag = // ... ComProtocol protocol = NFCProtocl.create(context, myNfcTag)// ...
// For bluetooth low energy communication // ONLY AVAILABLE in node.js environment import { NobleBleAdapter } from "@iotize/device-com-ble.node"; // Socket // ONLY AVAILABLE in node.js environment import { SocketProtocol } from "@iotize/device-com-socket.node"; let protocol = new SocketProtocol({ host: 'yourhost', port: 'yourport' }); // For websocket // AVAILABLE in browser or node.js import { WebSocketProtocol } from "@iotize/device-com-websocket.js"; let protocol = new WebSocketProtocol({ url: 'ws://yourhost:yourport' }); // MQTT // AVAILABLE in browser or node.js import { SocketProtocol } from "@iotize/device-com-mqtt.js"; let protocol = new MqttProtocol({ host: 'yourhost', port: 'yourport', // TODO });
Instantiate your device¶
Once you've pick a communication protocol you can instanciate a IoTizeDevice
object and connect to it.
// Instantiate your IoTideDevice object from the ComProtocol IoTizeDevice device = IoTizeDevice.fromProtocol(comProtocol); // Connect to the device device.connect();
let protocol: ComProtocol = ... ; // Your protocol object (see above) let device = IoTizeDevice.create(); let connectionPromise: Promise<void> = device.connect(protocol); connectionPromise .then(() => { // You are now connected and ready to send commands }) .catch((err: Error) => { // An error occured during connection (timeout, unreachable, ...) });
Send commands¶
Once you are connected to an IoTize device, you can perform IoTize device API calls.
Available commands are organized into multiple services. See the list of services and functions available here: IoTizeDeviceServices (android javadoc)
Let's try to read the serial number from the IoTize Device. We will use the command IoTizeDeviceServices
IoTizeDevice device = IoTizeDevice.fromProtocol( // Your protocol ); Call<String> commandCall = device.services.device.getSerialNumber(); // Execute command synchronously Response<String> response = commandCall.execute(); if (response.isSuccessful()){ String serialNumber = response.body(); Log.i("yourtag", "Serial number is : " + serialNumber); } else{ Log.w("yourtag", "Iotize error code: " + response.codeRet()); } // OR execute asynchronously commandCall.enqueue(new ICallback<String>() { @Override public void onResponse(Call<String> call, Response<String> response) { if (response.isSuccessful()){ String serialNumber = response.body(); Log.i("yourlogtag", "Serial number is : " + serialNumber); } else{ Log.w("yourtag", "Iotize error code: " + response.codeRet()); } } @Override public void onFailure(Call<String> call, Throwable throwable) { Log.e("yourlogtag", "Error occured: " + throwable.getMessage(), throwable); } });
let device: IoTizeDevice = ...; // Device object you have created above // Make sure you are connected console.log(`Is device connected: ${device.isConnected()}`); // Should return true let responsePromise = device.service.device.getSerialNumber(); responsePromise .then((response: Response<string>) => { // Received a response from the device, is does not mean that request was successfull // You must check response here if (response.isSuccess()){ let serialNumber = response.body(); // Calling .body() with throw an error if request was not successfull // Do whatever you want with the serial number... } else{ console.error(`Unsuccessfull response with error code: ${response.codeRet()}`); } }) .catch((err) => { // No response from device (ie: device is not connected or request timeout) }); // OR sugar synthax with await: try{ let serialNumber = (await device.service.device.getSerialNumber()).body(); } catch (ex){ // No response from device (ie: device is not connected or request timeout) }