sdk-xyo-android

The XYO Foundation provides this source code available in our efforts to advance the understanding of the XYO Procotol and its possible uses. We continue to maintain this software in the interest of developer education. Usage of this source code is not intended for production.

Table of Contents

• Title
• Description
• Gradle Build
• Maven Build
• Examples
• Usage
• Architecture
• Maintainers
• Contributing
• License
• Credits

Description 

A high-level SDK for interacting with the XYO network. Including BLE, TCP/IP, Bound Witnessing, and Bridging. Use this instead of sdk-core-kotlin for integration with your app project.

As you are developing on the SDK, be sure to keep an eye out for updates, as they may include core and ble updates

Gradle Build

    compile 'network.xyo:sdk-xyo-android:3.1.38'

Maven Build

<dependency>
  <groupId>network.xyo</groupId>
  <artifactId>sdk-xyo-android</artifactId>
  <version>3.1.38</version>
  <type>pom</type>
</dependency>

Permissions and Set Up

When using Android Studio and an Android device to test BLE Client and Server be sure to enable permissions and add an initialization function in your MainActivity

AndroidManifest.xml

    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
    <uses-permission android:name="android.permission.BLUETOOTH" />

MainActivity.kt

GlobalScope.launch {
  // place initialization function here for node build needed
  // you can look at the sample app for code example
}

Examples

Copy this code to test. Look below for specific usage.

One line is all it takes to start your node

val node = XyoNodeBuilder().build(context)

For a more complex test, create a listener callback.

  // callback for node events
          val listener = object : XyoBoundWitnessTarget.Listener() {
              override fun boundWitnessCompleted(boundWitness: XyoBoundWitness?, error: String?) {
                  super.boundWitnessCompleted(boundWitness, error)

                  println("New bound witness!")
              }

              override fun boundWitnessStarted() {
                  super.boundWitnessStarted()

                  println("Bound witness started!")

              }
          }       

You can also configure to your specific roles.

          // build and configure the node
          val builder = XyoNodeBuilder()
          builder.setListener(listener)

          // create the node
          val context = getContextSomehow()
          val node = builder.build(context)

          // configure tcp
          val tcpNetwork = node.networks["tcpip"] ?: return
          tcpNetwork.client.autoBridge = true
          tcpNetwork.client.autoBoundWitness = true
          tcpNetwork.client.scan = false
          tcpNetwork.client.knownBridges = ["public key of bridge", "public key of bridge"]

          // configure ble
          val bleNetwork = node.networks["ble"] ?: return
          bleNetwork.client.autoBridge = true
          bleNetwork.client.autoBoundWitness = true
          bleNetwork.client.scan = false

You can also use a heuristic getter, here is an example to get GPS.

    (node.networks["ble"] as? XyoBleNetwork)?.client?.relayNode?.addHeuristic(
        "GPS",
        object: XyoHeuristicGetter {
            override fun getHeuristic(): XyoObjectStructure? {
                val locationManager = applicationContext.getSystemService(Context.LOCATION_SERVICE) as LocationManager

                if (ContextCompat.checkSelfPermission(applicationContext, android.Manifest.permission.ACCESS_FINE_LOCATION)
                    == PackageManager.PERMISSION_GRANTED) {
                    val lastLocation = locationManager.getLastKnownLocation(LocationManager.GPS_PROVIDER)

                    if (lastLocation != null) {
                        val encodedLat = ByteBuffer.allocate(8).putDouble(lastLocation.latitude).array()
                        val encodedLng = ByteBuffer.allocate(8).putDouble(lastLocation.longitude).array()
                        val lat = XyoObjectStructure.newInstance(XyoSchemas.LAT, encodedLat)
                        val lng = XyoObjectStructure.newInstance(XyoSchemas.LNG, encodedLng)

                        return XyoIterableStructure.createUntypedIterableObject(XyoSchemas.GPS, arrayOf(lat, lng))
                    }
                }
                return null
            }
        }
    )

Usage

Build an XYO Node

val builder = XYONodeBuilder()

After calling the node builder, you can start the build

val node = XyoNode()

node = builder.build(this)

Once you have a build, you have access to properties to help you shape your node and what you want out of it.

node.networks["this can be "ble" or "tcpip""]

After choosing the network, you have these properties available

Client

// select the network
val network = node.networks["network"]

// a flag to tell the client to automatically bridge
network.client.autoBridge

// a flag to tell the client to automatically bound witness 
network.client.autoBoundWitness

// a flag to tell the client to automatically scan
network.client.scan

Server

// select the network 
val network = node.networks["network"]

// a flag to tell the server to automatically bridge
network.server.autoBridge

// a flag to tell the client to automatically listen for bridging
network.server.listen

These will allow your app to actively seek devices to bound witness with and bridge from the client to the server.

You can also get payload data from the bound witness

node.listener.getPayloadData(target: XyoBoundWitnessTarget)

This will return a byteArray.

There are other properties from the client and server which you can find in the source code as well as a reference guide that we have prepared.

Architecture

This sdk is built on a client/server to ensure ease of understanding during development. (The client takes on "central" role, and the server the "peripheral"). This allows us to define roles with simplicity. 

SDK-XYO-ANDROID TREE

• XyoSDK
  • mutableList <XyoNode>
    • XyoNode(storage, networks)
      • listeners
        • boundWitnessTarget
    • XyoClient, XyoServer

      • Ble

        • context
        • relayNode
        • procedureCatalog
        • autoBridge
        • acceptBridging
        • autoBoundWitness
        • scan

      • TcpIp

        • relayNode
        • procedureCatalog
        • autoBridge
        • acceptBridging
        • autoBoundWitness

Sample App

Please refer to the xyo-android-sample for an exmple implementation for bound witness and bridging. 

Install

To use the sample app to measure functionality

• Launch Android Studio
• Click on Open an existing Android Studio Project
• Navigate to <path to the sdk-xyo-android>/xyo-android-sample in your file explorer

Once you open the sample in Android Studio it will execute the build.

You can then run the app in a simulator of your choice or an Android device. 

This sample app includes client bridging and bound witnessing with a BLE server listener.

Maintainers

• Arie Trouw

Contributing

Please note that any contributions must clear the release branch.

License

See the LICENSE file for license details.

Credits

Made with 🔥and ❄️ by XYO