IoticAgent.IOT.Thing module¶

Wrapper object for Iotic Things

class IoticAgent.IOT.Thing.Thing(client, lid, guid, epId)¶

Bases: IoticAgent.IOT.Resource.Resource

Thing class

agent_id¶

Agent id (aka epId) with which this Thing is associated. None indicates this Thing is not assigned to any agent. The following actions can only be performed with a Thing if operating in its associated agent:

Receive feed data from feeds the Thing is following
Share feed data for feeds this Thing owns
Receive control requests for controls the Thing owns
Perform ask/tell on a control this Thing is attached to

Attempting to perform the above actions from another agent will result in either a local (e.g. ValueError) or remote exception to be raised(IoticAgent.IOT.Exceptions module).

attach(gpid)¶

Create a subscription (i.e. attach) to a Control-Point with a global point id (gpid) and a feed data callback

Returns:	A new RemoteControl object from the IoticAgent.IOT.RemotePoint module or the existing one if the subscription already exists
Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	gpid (lid, pid) – Global id of the Point to which you want to attach OR gpid – Tuple of (thing_localid, point_localid) for local subscription

attach_async(gpid)¶

create_control(pid, callback, callback_parsed=None)¶

Create a control for this Thing with a local point id (pid) and a control request feedback

Returns:	A new IoticAgent.IOT.Point module control object or the existing one if the Control already exists
Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	pid (string) – Local id of your Control callback (function reference) – Callback function to invoke on receipt of a control request. callback_parsed (function reference, optional) – Callback function to invoke on receipt of control data. This is equivalent to callback except the dict includes the parsed key which holds the set of values in a IoticAgent.IOT.Point module PointDataObject instance. If both callback_parsed and callback` have been specified, the former takes precedence and callback is only called if the point data could not be parsed according to its current value description.

The callback receives a single dict argument, with keys of:

'data'      # (decoded or raw bytes)
'mime'      # (None, unless payload was not decoded and has a mime type)
'subId'     # (the global id of the associated subscripion)
'entityLid' # (local id of the Thing to which the control belongs)
'lid'       # (local id of control)
'confirm'   # (whether a confirmation is expected)
'requestId' # (required for sending confirmation)

Note

callback_parsed can only be used if auto_encode_decode is enabled for the client instance.

create_control_async(pid, callback, callback_parsed=None)¶

create_feed(pid, save_recent=0)¶

Create a new Feed for this Thing with a local point id (pid).

Returns:	A new IoticAgent.IOT.Point module feed object, or the existing one, if the Feed already exists
Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	pid (string) – Local id of your Feed save_recent (int, optional) – How many shares to store for later retrieval. If not supported by container, this argument will be ignored. A value of zero disables this feature whilst a negative value requests the maximum sample store amount.

create_feed_async(pid, save_recent=0)¶

create_property(props, replace=True, replace_all=False)¶

Create RDF properties for a Thing, given as a list of predicate-object tuples. Strs, bools, ints, and floats will be automatically cast to the correct XSD type; any other type must be given as a third member of the tuple. Strings can be given a language with two @’s and the two-letter language code at the end, e.g. “Fritz@@de”. Iotic internal properties cannot be altered.

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	props (list) – The sequence of properties (or single property) you want to add to your Thing replace (bool) – Whether to delete all existing properties for the given predicates before adding new ones. replace_all (bool) – Whether to delete all existing properties for ALL predicates before adding new ones.

create_tag(tags)¶

Create tags for a Thing in the language you specify. Tags can only contain alphanumeric (unicode) characters and the underscore. Tags will be stored lower-cased.

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	tags (list) – The list of tags (or single one) you want to add to your Thing, e.g. [“garden”, “soil”]

delete_control(pid)¶

Delete a control, identified by its local id.

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	pid (string) – Local identifier of your control you want to delete

delete_control_async(pid)¶

delete_feed(pid)¶

Delete a feed, identified by its local id.

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	pid (string) – Local identifier of your feed you want to delete

delete_feed_async(pid)¶

delete_property(props)¶

Delete RDF properties for a Thing. Properties should be given as a list of predicate-object tuples as shown in the create_property method; however, unlike that method, None can be given as an object, having the effect of deleting all the properties for that predicate. Also, an empty list can be passed, deleting all non-internal properties. Iotic internal properties cannot be altered.

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	properties (list) – The sequence of properties (or single property) you want to delete from your Thing

delete_tag(tags)¶

Delete tags for a Thing in the language you specify. Case will be ignored and any tags matching lower-cased will be deleted.

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	tags (list) – The list of tags (or single one) you want to delete from your Thing, e.g. [“garden”, “soil”]

follow(gpid, callback=None, callback_parsed=None)¶

Create a subscription (i.e. follow) a Feed/Point with a global point id (gpid) and a feed data callback

Returns:	A new IoticAgent.IOT.RemotePoint module RemoteFeed object or the existing one if the subscription already exists

Or:

Raises:

IOTException – Infrastructure problem detected
LinkException – Communications problem between you and the infrastructure

Parameters:

gpid (lid, pid) – Global id of the Point you want to follow OR
gpid – Tuple of (thing_localid, point_localid) for local subscription
callback (function reference, optional) – Callback function to invoke on receipt of feed data.
callback_parsed (function reference, optional) – Callback function to invoke on receipt of feed data. This is equivalent to callback except the dict includes the parsed key which holds the set of values in a IoticAgent.IOT.Point module PointDataObject instance. If both callback_parsed and callback have been specified, the former takes precedence and callback is only called if the point data could not be parsed according to its current value description.

Note

The callback receives a single dict argument, with keys of:

'data' # (decoded or raw bytes)
'mime' # (None, unless payload was not decoded and has a mime type)
'pid'  # (the global id of the feed from which the data originates)
'time' # (datetime representing UTC timestamp of share)

Note

callback_parsed can only be used if auto_encode_decode is enabled for the client instance.

follow_async(gpid, callback=None, callback_parsed=None)¶

get_control(pid)¶

Get the details of a newly created control. This only applies to asynchronous creation of feeds and the new control instance can only be retrieved once.

Note

Destructive Read. Once you’ve called get_control once, any further calls will raise a KeyError

Returns:	A IoticAgent.IOT.Point module control object, which corresponds to the cached entry for this local control id
Parameters:	pid (string) – Local identifier of your control.
Raises:	`KeyError` – The control has not been newly created (or has already been retrieved by a previous call)

get_feed(pid)¶

Get the details of a newly created feed. This only applies to asynchronous creation of feeds and the new feed instance can only be retrieved once.

Note

Destructive Read. Once you’ve called get_feed once, any further calls will raise a KeyError

Returns:	A IoticAgent.IOT.Point module feed object, which corresponds to the cached entry for this local feed id.
Parameters:	pid (string) – Point id - local identifier of your feed.
Raises:	`KeyError` – Feed has not been newly created (or has already been retrieved by a previous call)

get_meta()¶

Get the metadata object for this Thing

Returns:	A IoticAgent.IOT.ThingMeta module object

get_meta_rdf(fmt='n3')¶

Get the metadata for this Thing in rdf fmt.

Advanced users who want to manipulate the RDF for this Thing directly without the IoticAgent.IOT.ThingMeta module helper object.

Returns:	The RDF in the format you specify

OR

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	fmt (string, optional) – The format of RDF you want returned. Valid formats are: “xml”, “n3”, “turtle”

get_remote_control(gpid)¶

Retrieve RemoteControl instance for an attach. This only applies to asynchronous attach requests and the new RemoteControl instance can only be retrieved once.

Note

Destructive Read. Once you’ve called get_remote_control once, any further calls will raise a KeyError

Raises:	`KeyError` – If the attach-subscription has not been newly created (or has already been retrieved by a previous call) `ValueError` – If the followed Point is actually a feed instead of a control, or if the subscription has not completed yet.

get_remote_feed(gpid)¶

Retrieve RemoteFeed instance for a follow. This only applies to asynchronous follow requests and the new RemoteFeed instance can only be retrieved once.

Note

Destructive Read. Once you’ve called get_remote_feed once, any further calls will raise a KeyError

Raises:	`KeyError` – The follow-subscription has not been newly created (or has already been retrieved by a previous call `ValueError` – The followed Point is actually a control instead of a feed, or if the subscription has not completed yet.

lid¶: The local id of this Thing. This is unique to you on this container. Think of it as a nickname for the Thing

list_connections(limit=500, offset=0)¶

List Points to which this Things is subscribed. I.e. list all the Points this Thing is following and controls it’s attached to

Returns:	Subscription list e.g.

{
    "<Subscription GUID 1>": {
        "id": "<Control GUID>",
        "entityId":  "<Control's Thing GUID>",
        "type": 3  # R_CONTROL from IoticAgent.Core.Const
    },
    "<Subscription GUID 2>": {
        "id": "<Feed GUID>",
        "entityId":  "<Feed's Thing GUID>",
        "type": 2  # R_FEED from IoticAgent.Core.Const
}

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure

Note

For Things following a Point see IoticAgent.IOT.Point module list_followers.

list_controls(limit=500, offset=0)¶

List all the controls on this Thing.

Returns:	QAPI list function payload
Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	limit (integer, optional) – Return this many Point details offset (integer, optional) – Return Point details starting at this offset

list_feeds(limit=500, offset=0)¶

List all the feeds on this Thing.

Returns:	QAPI list function payload
Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	limit (integer, optional) – Return this many Point details offset (integer, optional) – Return Point details starting at this offset

list_property(limit=500, offset=0)¶

List all the properties for this Thing

Returns:	dict with predicates as keys and object lists as values, with RDF Literals converted to the format given as input to create_property (ie, XSD type as extra tuple member where required, language via ‘@@en’ suffix). Iotic-internal properties omitted. Eg:

{
    "http://xmlns.com/foaf/0.1/age": [
        31
    ],
    "http://my.domain.net/some/ontology#customPredicate": [
        55.4
    ],
    "http://my.domain.net/some/ontology#someFlag": [
        True
    ],
    "http://my.domain.net/some/ontology#someProperty": [
        "A string without language"
    ],
    "http://my.domain.net/some/ontology#anotherProperty2": [
        "Language-specific string@@en"
    ],
    "http://www.w3.org/1999/02/22-rdf-syntax-ns#type": [
        "http://some.company.org/my-types/oven",
        "http://some.company.org/my-types/hob"
    ],
    "http://my.domain.net/some/ontology#anotherProperty": [
        "The english text@@en",
        "Die deutsche Version@@de"
    ],
    "http://my.domain.net/some/ontology#buildMonth": [
        ("2019-11", "gYearMonth")
    ],
    "http://my.domain.net/some/ontology#purchaseTime": [
        ("2018-10-10T12:00:00Z", "dateTime"),
        ("2019-11-12T14:21:44Z", "dateTime")
    ]
}

Or:

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	limit (integer, optional) – Return at most this many properties offset (integer, optional) – Return properties starting at this offset

list_tag(limit=500, offset=0)¶

List all the tags for this Thing

Returns:	Lists of tags, as below

[
    "mytag1",
    "mytag2"
    "ein_name",
    "nochein_name"
]

Or:

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	limit (integer, optional) – Return at most this many tags offset (integer, optional) – Return tags starting at this offset

reassign(new_epid)¶

Reassign the Thing from one agent to another.

Advanced users only

This will lead to any local instances of a Thing being rendered useless. They won’t be able to receive control requests, feed data or to share any feeds as they won’t be in this agent.

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	new_epid (string) – The new agent id to which your Thing should be assigned. If None, current agent will be chosen. If False, existing agent will be unassigned.

rename(new_lid)¶

Rename the Thing.

Advanced users only

This can be confusing. You are changing the local id of a Thing to new_lid. If you create another Thing using the “old_lid”, the system will oblige, but it will be a completely new Thing.

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	new_lid (string) – The new local identifier of your Thing

set_meta_rdf(rdf, fmt='n3')¶

Set the metadata for this Thing in RDF fmt.

Advanced users who want to manipulate the RDF for this Thing directly without the IoticAgent.IOT.ThingMeta module helper object.

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	fmt (string, optional) – The format of RDF you have sent. Valid formats are: “xml”, “n3”, “turtle”

set_public(public=True)¶

Sets your Thing to be public to all if public=True. This means the tags, label and description of your Thing are now searchable by anybody, along with its location and the units of any values on any Points.

If public=False the metadata of your Thing is no longer searchable.

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	public (boolean, optional) – Whether (or not) to allow your Thing’s metadata to be searched by anybody

unattach(subid)¶

Remove a subscription of a control with a global subscription id (gpid)

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	subid (object) – Global id of the subscription you want to delete OR subid – The instance of a RemoteControl object corresponding to the control you want to cease being able to actuate.

unfollow(subid)¶

Remove a subscription of a Feed with a global subscription id (gpid)

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	subid (object) – Global id of the subscription you want to delete OR subid – The instance of a RemoteFeed object corresponding to the feed you want to cease following.