Archive - Tutorial 4 - Adding properties

❗️

Opps

This page has been deprecated, if you have found your way here please head back to the Welcome page!

Now that we know how to search for Twins, we can start looking at specific properties of twins and how to work with them. By the end of this tutorial you will be able to add properties to a twin and then search by properties.

Overview

Properties allow you to add additional information Twins, enabling more granular information and complex relationships to be built into your ecosystem. For example you could give your twins Categories or list the Manu factory of machinery allowing you to easily find all the twins that match your interest.

Properties are expressed as key value pair with value expressed with an optional unit.

Before you begin

Make sure you create a file with the content in the “Bring it all together” of Tutorial 2 . You can then run that file in the REPL with:

exec(open("./iotics_tutorial.py").read())

Adding properties to a twin

To add properties to a Twin we just send a payload with
Let’s add properties to the hb_twin:

payload = {
    "properties": [
        {
            "key": "http://data.iotics.com/ns/category",
            "uriValue": {
                "value": "http://data.iotics.com/category/Health"
            }
        },
        {
            "key": "http://demo.iotics.com/ont/ev/has_backup",
            "literalValue": {
                "dataType": "boolean",
                "value": "true"
            }
        },
        {
            "key": "http://demo.iotics.com/ont/ev/maker",
            "stringLiteralValue": {
                "value": "HBMaker LTD"
            }
        }
    ]
}

r = requests.patch(f'{host.address}/qapi/twins/{hb_twin_identity.id}',
                   headers=iotics_headers(
                       agent_identity, user_identity, host.address),
                   data=json.dumps(payload))

You can find more information on properties in the Update a Twin section of our API reference.

Search by properties

To search by properties it’s necessary to set a properties filter to the search request.

stomp_client.set_listener("log_listener", PrintingListener())

token = agent2_identity.document_manager.new_token(principal_did=user_key.id, duration=3600, audience=host.address)
stomp_client.connect(wait=True, passcode=token)

search_payload={
  "filter": {
    "text": "monitor",
    "properties": [
      {
        "key": "http://demo.iotics.com/ont/ev/has_backup",
        "literalValue": {
          "dataType": "boolean",
          "value": "true"
        }
      }
    ]
  },
  "expiryTimeout": "2000-01-23T04:56:07+00:00"
}

stomp_client.subscribe(destination="/qapi/searches/results", id=1, headers=iotics_stomp_headers(agent2_identity))

stomp_client.send('/qapi/searches/dispatches', headers=iotics_stomp_headers(agent2_identity), body=json.dumps(search_payload))

Running the search request will print responses from the hosts in the network with results. Since we set a property filter on the twin we expect only one twin in the response as:

{
    "responseType": "FULL",
    "twins": [{
        "id": {
            "value": "did:iotics:iotACEiy53BLXeRyTmTbu3VL4pNF6VYAfyWf"
        },
        "location": {
            "lat": 0.0,
            "lon": 0.0
        },
        "label": "heartbeat monitor",
        "tags": ["cat_health", "monitor"],
        "properties": [{
            "key": "http://data.iotics.com/ns/category",
            "uriValue": {
                "value": "http://data.iotics.com/category/Health"
            }
        }, {
            "key": "http://demo.iotics.com/ont/ev/has_backup",
            "literalValue": {
                "dataType": "boolean",
                "value": "true"
            }
        }, {
            "key": "http://demo.iotics.com/ont/ev/maker",
            "stringLiteralValue": {
                "value": "HBMaker LTD"
            }
        }],
        "feeds": [{
            "feed": {
                "id": {
                  "value": "hb"
                  },
                "twinId": {
                    "value": "did:iotics:iotACEiy53BLXeRyTmTbu3VL4pNF6VYAfyWf"
                }
            },
            "label": "bpm",
            "storeLast": true
        }]
    }]
}

Bring it all together

Copy this content in iotics_tutorial.py to set the state of your env to include the work in this tutorial

import json
import base64
import requests
import shortuuid
from iotic.lib.identity import Identifier
from iotics_id import Host, NamedECDSAKey, DocumentManager, IdentifiableEntity
from random import randrange
from datetime import datetime
from iotic.web.stomp.client import StompWSConnection12
from stomp.listener import PrintingListener


host = Host("https://api01.demo02.space.iotics.com")

seed = None
try:
    seed = open('.seed', 'r').read()
except:
    # no file
    seed = Identifier.new_seed(256)
    f = open(".seed", "a")
    f.write(seed)
    f.close()


def getHB(min, max):
    return min + randrange(max - min)


def share(host: str, headers: dict, twin_id: str, feed_id: str):
    message = json.dumps({"bpm": getHB(50, 90)})
    message_b64 = base64.b64encode(message.encode('ascii')).decode('ascii')
    payload = {
        "sample": {
            "data": message_b64,
            "mime": "application/json;encoding=base64",
            "occurredAt": datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%S%zZ')
        }
    }
    r = requests.post(f'{host}/qapi/twins/{twin_id}/feeds/{feed_id}/shares',
                      headers=headers, json=payload)
    print(f'"shared {message}: result code={r.status_code}')


def iotics_headers(agent_identity: IdentifiableEntity, user_identity: IdentifiableEntity, host: str, duration: int = 120) -> dict:
    user_did = user_identity.document_manager.named_key.id
    token = agent_identity.document_manager.new_token(
        principal_did=user_did, duration=duration, audience=host)
    headers = {
        "accept": "application/json",
        "Iotics-ClientRef": f'd-poc-{shortuuid.random(8)}',
        "Iotics-ClientAppId": agent_identity.document_manager.named_key.id,
        "Authorization": f'Bearer {token}',
        "Content-Type": "application/json"
    }
    return headers


print("creating/retrieving user and agent identity + delegation")
user_key = NamedECDSAKey(seed=seed, purpose="user", name="fred_at_gmail-0")
user_identity = IdentifiableEntity(named_key=user_key, host=host)

agent_key = NamedECDSAKey(seed=seed, purpose="agent", name="hb-mon-0")
agent_identity = IdentifiableEntity(named_key=agent_key, host=host)
agent_proof = agent_identity.document_manager.new_proof(did=user_key.id)

agent_issuer = agent_identity.document_manager.issuer()

user_identity.document_manager.add_auth_delegation(
    proof=agent_proof, authorizer_id=agent_issuer, name="agent_deleg_0")

print("creating twin identity")
hb_twin_key = NamedECDSAKey(seed=seed, purpose="twin", name="hb_device_001")
hb_twin_identity = IdentifiableEntity(named_key=hb_twin_key, host=host)
agent_proof = agent_identity.document_manager.new_proof(
    did=hb_twin_identity.id)
agent_issuer = agent_identity.document_manager.issuer()
deleg_name = f'{agent_identity.document_manager.named_key.name}_0'
print("delegating agent to control twin")
hb_twin_identity.document_manager.add_control_delegation(
    proof=agent_proof, controller_id=agent_issuer, name=deleg_name)

print("making the twin resource")
payload = {'twinId': {'value': hb_twin_identity.id}}
r = requests.post(f'{host.address}/qapi/twins', headers=iotics_headers(
    agent_identity, user_identity, host.address), json=payload)

payload = {
    "tags": {
        "added": ["cat_health", "monitor"]
    },
    "labels": {
        "added": [
            {"lang": "en", "value": "heartbeat monitor"}
        ]
    },
    "comments": {
        "added": [
            {"lang": "en", "value": "an heartbeat monitor"}
        ]
    }
}

r = requests.patch(f'{host.address}/qapi/twins/{hb_twin_identity.id}',
                   headers=iotics_headers(
                       agent_identity, user_identity, host.address),
                   data=json.dumps(payload))

print("making the feed resource")
name = 'hb'
payload = {"feedId": {"value": name}, "storeLast": True}
r = requests.post(f'{host.address}/qapi/twins/{hb_twin_identity.id}/feeds',
                  headers=iotics_headers(agent_identity, user_identity, host.address), json=payload)

payload = {
    "comments": {
        "added": [
          {
              "lang": "en",
              "value": "the beat per minutes"
          }
        ]
    },
    "storeLast": True,
    "labels": {
        "added": [
            {
                "lang": "en",
                "value": "bpm"
            }
        ]
    },
    "values": {
        "added": [
            {
                "comment": "bpm",
                "dataType": "decimal",
                "label": "bpm",
                "unit": "http://purl.obolibrary.org/obo/UO_0000148"
            }
        ]
    }
}
r = requests.patch(f'{host.address}/qapi/twins/{hb_twin_identity.id}/feeds/{name}',
                   headers=iotics_headers(agent_identity, user_identity, host.address), json=payload)

print("publishing sample data")
message = json.dumps({"bpm": 70})
message_b64 = base64.b64encode(message.encode('ascii')).decode('ascii')
payload = {
    "sample": {
        "data": message_b64,
        "mime": "application/json;encoding=base64",
        "occurredAt": datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%S%zZ')
    }
}

requests.post(f'{host.address}/qapi/twins/{hb_twin_identity.id}/feeds/{name}/shares',
              headers=iotics_headers(agent_identity, user_identity, host.address), json=payload)

print("create another agent")

agent2_key = NamedECDSAKey(seed=seed, purpose="agent", name="hrate_mon_0")
agent2_identity = IdentifiableEntity(named_key=agent2_key, host=host)

agent2_proof = agent2_identity.document_manager.new_proof(did=user_key.id)
agent2_issuer = agent2_identity.document_manager.issuer()
user_identity.document_manager.add_auth_delegation(
    proof=agent2_proof, authorizer_id=agent2_issuer, name="hrate_mon_0_deleg_0")

print("create another twin")
hrate_monitor_twin_key = NamedECDSAKey(
    seed=seed, purpose="twin", name="hrate_monitor_001")
hrate_monitor_twin_identity = IdentifiableEntity(
    named_key=hrate_monitor_twin_key, host=host)

payload = {'twinId': {'value': hrate_monitor_twin_identity.id}}
requests.post(f'{host.address}/qapi/twins', headers=iotics_headers(
    agent_identity, user_identity, host.address), json=payload)

print("create a stomp client")

resp = requests.get(f'{host.address}/index.json').json()
stomp_endpoint = resp["stomp"]
stomp_client = StompWSConnection12(endpoint=stomp_endpoint)
stomp_client.set_ssl(verify=False)


def iotics_stomp_headers(agent_identity: IdentifiableEntity) -> dict:
    return {
        "Iotics-ClientRef": f'd-poc-{shortuuid.random(8)}',
        "Iotics-ClientAppId": agent_identity.document_manager.named_key.id
    }


payload = {
    "properties": {
        "added": [
            {
                "key": "http://data.iotics.com/ns/category",
                "uriValue": {
                    "value": "http://data.iotics.com/category/Health"
                }
            },
            {
                "key": "http://demo.iotics.com/ont/ev/has_backup",
                "literalValue": {
                    "dataType": "boolean",
                    "value": "true"
                }
            },
            {
                "key": "http://demo.iotics.com/ont/ev/maker",
                "stringLiteralValue": {
                    "value": "HBMaker LTD"
                }
            }
        ]}
}


r = requests.patch(f'{host.address}/qapi/twins/{hb_twin_identity.id}',
                   headers=iotics_headers(
                       agent_identity, user_identity, host.address),
                   data=json.dumps(payload))

Did this page help you?