Skip to main content

Getting Started

info

This plugin allows you to Work with BLE Mesh Devices using Golain SDKs and use the Golain Platform APIs in your Flutter apps.

info

If you want to treat the mobile application as a device and connect it to the Golain Platform, you can use the Golain Mobile MQTT SDK.

Introduction​

  • The Golain Mobile SDK is designed to provide you the following features :
    • Loading a Mesh Network from the Golain Cloud.
    • Resetting a Mesh network
    • Importing an existing mesh network
    • Exporting an existing mesh network
    • Scanning for unprovisioned devices
    • Provision devices
    • Scan for provisioned devices
    • Connect to devices
    • Send and recieve data to and from devices using the custom Golain Vendor model.
    • Deprovision node

Pre-requisites​

  • Define a Protobuf structure for your device data.

    • Refer to the following to learn how to define a protobuf structure here.

    • Let us take an example of a proto file.

    •  // Name of the file : message.proto

       syntax = "proto3";

       message shadow {
       int32 red = 1;
       int32 green = 2;
       int32 blue = 3;
       }

    • Once the proto file is defined, install the protoc compiler to compile the proto file into dart code.

      • For linux users, execute the following command to install the protoc compiler.

        $ apt install -y protobuf-compiler
        $ protoc --version  # Ensure compiler version is 3+

      • For mac users, execute the following command to install the protoc compiler.

        $ brew install protobuf
        $ protoc --version  # Ensure compiler version is 3+

    • To generate the dart code for the protobuf structure.

      • Install the dart plugin for protoc.

        $ dart pub global activate protoc_plugin

      • Make sure you have ~/.pub-cache/bin in your PATH.

      • This method installs a Dart script and requires presence of dart executable in your PATH.

      • Execute the following command to generate the dart code for the protobuf structure. 

        protoc --dart_out=. --plugin=protoc-gen-dart=$HOME/.pub-cache/bin/protoc-gen-dart ./message.proto

        // here message.proto is the name of the proto file.

    • Install the dart dependency protobuf 

      •  $ flutter pub add protobuf

    • Add the generated dart code to your project. 

      • import 'message.pb.dart';

    • Encode the protobuf structure to a byte array. 

      • // Create a shadow object and set the values of the fields.

        var shadow = Shadow();
        shadow.red = 1;
        shadow.green = 2;
        shadow.blue = 3;
        var bytes = shadow.writeToBuffer();

    • This byte array would be sent to the device shadow.

    • It would be passed to the Golain Vendor model using the control plane and the data plane, which would be sent to the device.

  • The following Mobile SDK would work well with the Golain ESP Mesh SDK.

  • Must have BLE Mesh devices for the Golain Mobile SDK to connect to.

Installation Steps - Integrating the Golain SDK in your project​

Android :

  • Step 1 :

    Navigate to the pubspec.yaml file in your project and add the following dependency to the list of dependencies:


    golain:
    git:
      url: https://github.com/golain-io/flutter-platform-sdk.git
      ref: main

  • Step 2 :

    Makefile -

    Execute the following command in the terminal inorder to download and fetch Android /IOS NRF submodules.

    curl -o Makefile https://raw.githubusercontent.com/golain-io/flutter-platform-sdk/main/Makefile && make fetch-submodules

  • Step 3 :

    Navigate to the android/settings.gradle file in your project and add the following lines to the end of the file:


        // reuse app_plugin_loader.gradle code to include nested Android-nRF-Mesh-Library without hard-coding the directory path

     import groovy.json.JsonSlurper

     def flutterProjectRoot = rootProject.projectDir.parentFile

     // Note: if this logic is changed, also change the logic in module_plugin_loader.gradle.
     def pluginsFile = new File(flutterProjectRoot, '.flutter-plugins-dependencies')
     if (!pluginsFile.exists()) {
     return
     }

     def object = new JsonSlurper().parseText(pluginsFile.text)
     assert object instanceof Map
     assert object.plugins instanceof Map
     assert object.plugins.android instanceof List
     // Includes the Flutter plugins that support the Android platform.
     object.plugins.android.each { androidPlugin ->
     assert androidPlugin.name instanceof String
     assert androidPlugin.path instanceof String
     if(androidPlugin.name == 'nordic_nrf_mesh'){
         println 'should include forked Nordic\'s ADK v3'
         def meshLibPath = androidPlugin.path.replace('android', '') + 'Android-nRF-Mesh-Library-1\\mesh\\'
         println 'meshLibPath = ' + meshLibPath
         include ':mesh'
         project(':mesh').projectDir = file(meshLibPath)
     }
     }

  • Step 4 :

    Navigate to the android/app/build.gradle file in your project and set the following configuration:


    defaultConfig {
        minSdkVersion 23
    }

Setup​

  • Once, you've done with the installation steps, you can now start using the Golain SDK in your project.

Procedure :

  • Import the Golain SDK in your project : 

    import 'package:golain/golain.dart';

  • Initialize the Golain SDK : 

    Golain golain = Golain();

  • Load a mesh network from the Golain Cloud :

    • This will setup a functional mesh network where devices can be configured and can be provisioned. 
    • golain.loadMeshNetwork();

  • Reset a mesh network :

    • This will restore a mesh network to its default settings , effectively erasing all the custom configurations and data.

    • golain.resetMeshNetwork();

  • Import an existing mesh network :

    • This will bring an established mesh network into a new environment or system, without having to manually configure the network from scratch.
    • This function would take an input as a JSON file, which would contain the mesh network data, and that would be the exported file from the exportMeshNetwork() function.
    • golain.importMeshNetwork(File file);

  • Export an existing mesh network :

    • This will export the mesh network data as a JSON file, which can be used to import the mesh network into a new environment or system.

    • In the context of a mesh network, a JSON file may contain data and configurations such as:

    • Device information: including device IDs, names, and capabilities.

    • Network topology: including the relationships between devices and how they are connected.

    • Security settings: including keys and access permissions.

    • Routing tables: including information on how data is routed between devices.

    • Other network parameters: such as device roles, firmware versions, and network status.

    • golain.exportMeshNetwork();

  • Scanning for unprovisioned devices

    • This discovers and identifies devices that are not yet part of a mesh network and have not been assigned a unique identifier, known as a Provisioning Identifier (PID).
    •  golain.scanUnprovisionedDevices();
    • This returns a list of unprovisioned devices of type DISCOVERED DEVICE , which can be used to provision the devices.

  • Provisioning a device :

    • This assigns a unique identifier, known as a Provisioning Identifier (PID), to a device that is not yet part of a mesh network.
    • Once a device is provisioned, it can start participating in the network's activities, such as sending and receiving messages, and executing commands.
    • This function would take an input as a DISCOVERED DEVICE object, which would be returned from the scanUnprovisionedDevices() function.
    •  golain.provisionDevice(DiscoveredDevice device);
    • This returns a list of provisioned devices of type PROVISIONED DEVICE , which can be used to connect to the devices.

  • Scan for provisioned devices :

    • This discovers and identifies devices that are part of a mesh network and have been assigned a unique identifier, known as a Provisioning Identifier (PID).
    •  golain.provisionedNodesInRange();
    • This returns a list of provisioned devices of type DISCOVERED DEVICE, which can be used to connect to the devices.

  • Connect to a device :

    • Once a scanning device has initiated a connection request, the provisioned device can respond and establish a connection with the scanning device. This connection can be used for sending and receiving messages, executing commands, and other activities.

    • This function would take an input as a DISCOVERED DEVICE object, which would be returned from the scanProvisionedDevices() function.

    •    golain.connectToDevice(int companyId, DiscoveredDevice device);

    • Company Id is the company id of the device, which can be found in the device's datasheet.

  • Send and recieve data to and from devices using the custom Golain Vendor model.

    • The control plane and data plane are two distinct aspects of the network's operation that serve different purposes.
    • The control plane is responsible for managing and controlling the network's behavior, while the data plane is responsible for transporting data packets between devices in the network.
    • The control plane performs network management functions, such as routing and security, and operates at a higher level of abstraction than the data plane, which is optimized for high-speed data transport and is typically implemented in specialized hardware.

  • Control Plane

    • The control plane in Bluetooth Low Energy (BLE) mesh refers to the set of protocols and messages used for network management and control. It is responsible for tasks such as node discovery, formation and maintenance of the network topology, security management, and handling of control messages between nodes.

    • The control plane consists of various protocols and messages, such as the Mesh Profile specification, which defines the behavior and requirements for BLE mesh devices. These protocols and messages are used by nodes in the network to communicate with each other and to perform various functions such as assigning and updating network addresses, managing security keys, and routing messages between nodes.

    • The control plane plays an important role in ensuring the reliability and security of BLE mesh networks, as well as enabling the efficient communication and management of devices in the network.

    • The Golain SDK provides a control plane vendor model for sending and receiving data to and from devices.

    • the control plane in BLE mesh has both "set" and "get" functionalities.

    • Returns the message type of VendorModelMessageData

    • The "set" functionality allows a node to set or configure various network parameters such as node addresses, group addresses, publish/subscribe addresses, and other network settings. This is typically done during the initialization or configuration phase of the network, or when changes need to be made to the network configuration.

    • The "get" functionality, on the other hand, allows a node to request and receive information about various network parameters or states. For example, a node may use the "get" functionality to obtain information about the network topology, available services, or the status of other nodes in the network.

    • Both "set" and "get" functionalities are important for the proper functioning and management of the BLE mesh network. They enable nodes to interact with each other, share information, and perform various network management tasks, thereby ensuring the reliability, security, and efficiency of the network.

// Control Plane - SET

golain.controlPlaneSet(int elementAddress, int companyId, int opcode, Uint8List data);

// Control Plane - GET

golain.controlPlaneGet(int elementAddress, int companyId, int opcode, Uint8List data);

  • The parameters -

    • Element address : The element address of the device to which the data is to be sent.

    • Company id : The company id of the device to which the data is to be sent.

    • Opcode : The opcode of the data to be sent.

    • Data : The data to be sent, present in the form of a byte array.

  • The Golain SDK provides a data plane vendor model for only receiving data from devices.

  • Data Plane

    • The data plane in BLE mesh is responsible for transmitting application data between nodes using a publish/subscribe model. It is designed to be reliable and secure, with features such as message acknowledgment, retransmission, encryption, and support for large data payloads.
    • It is an important component of the network that enables efficient, scalable, and secure communication between nodes.

  • The Golain SDK provides a data plane vendor model for only receiving data from devices.

  • Returns the message type of VendorModelMessageData

        // Data Plane - GET

        golain.dataPlaneGet( int elementAddress, int companyId, int opcode, Uint8List data);

  • The parameters -

    • Element address : The element address of the device to which the data is to be sent.

    • Company id : The company id of the device to which the data is to be sent.

    • Opcode : The opcode of the data to be sent.

    • Data : The data to be sent, present in the form of a byte array.

  • Deprovisioning Node

    • This removes a device from a mesh network and restores it to its default settings, effectively erasing all the custom configurations and data.

    • golain.deprovisionNode(int unicastAddress, int timeoutDuration);