IoticAgent.IOT.Point module¶

Wrapper object for Iotic Points.

Points are come in two types:

Feed’s where they output data from a Thing
Control’s where they are a way of sending data to a Thing

class IoticAgent.IOT.Point.Control(client, lid, pid, guid)¶

Bases: IoticAgent.IOT.Point.Point

Controls are where a Thing invites others to send it data. Controls can be used to activate some hardware, reset counters, change reporting intervals - pretty much anything you want to change the state of a Thing. Controls are many-to-one.

class IoticAgent.IOT.Point.Feed(client, lid, pid, guid)¶

Bases: IoticAgent.IOT.Point.Point

Feeds are advertised when a Thing has data to share. They are for out-going data which will get shared with any remote Things that have followed them. Feeds are one-to-many.

get_recent_info()¶

Retrieves statistics and configuration about recent storage for this Feed.

Returns:	QAPI recent info function payload

{
    "maxSamples": 0,
    "count": 0
}

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

get_template()¶: Get new IoticAgent.IOT.PointValueHelper module PointDataObject instance to use for sharing data.

set_recent_config(max_samples=0)¶

Update/configure recent data settings for this Feed. If the container does not support recent storage or it is not enabled for this owner, this function will have no effect.

Parameters:	max_samples (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.
Returns:	QAPI recent config function payload

{
    "maxSamples": 0
}

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

share(data, mime=None, time=None)¶

Share some data from this Feed

Raises:

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

Parameters:

data – The data you want to share
time (datetime) – UTC time for this share. If not specified, the container’s time will be used. Thus it makes almost no sense to specify datetime.utcnow() here. This parameter can be used to indicate that the share time does not correspond to the time to which the data applies, e.g. to populate recent storage with historical data.
mime (string) – The mime type of the data you’re sharing. There are some Iotic Labs-defined default values.

“idx/1” corresponds to “application/ubjson” - the recommended way to send mixed data. Share a python dictionary as the data and the agent will to the encoding and decoding for you.

data = {}
data["temperature"] = self._convert_to_celsius(ADC.read(1))
# ...etc...
my_feed.share(data)

“idx/2” Corresponds to “text/plain” - the recommended way to send textual data. Share a utf8 string as data and the agent will pass it on, unchanged.

my_feed.share(u"string data")

“text/xml” or any other valid mime type. To show the recipients that: you’re sending something more than just bytes

my_feed.share("<xml>...</xml>".encode('utf8'), mime="text/xml")

share_async(data, mime=None, time=None)¶

class IoticAgent.IOT.Point.Point(client, lid, pid, guid)¶

Bases: IoticAgent.IOT.Resource.Resource

create_tag(tags)¶

Create tags for a Point 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 you want to add to your Point, e.g. [“garden”, “soil”]

create_value(label, vtype, lang=None, description=None, unit=None)¶

Create a value on this Point. Values are descriptions in semantic metadata of the individual data items you are sharing (or expecting to receive, if this Point is a control). This will help others to search for your feed or control. If a value with the given label (and language) already exists, its fields are updated with the provided ones (or unset, if None).

Raises:

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

Parameters:

label (string) – The label for this value e.g. “Temperature”. The label must be unique for this Point. E.g. You can’t have two data values called “Volts” but you can have “volts1” and “volts2”.
lang (string, optional) – The two-character ISO 639-1 language code to use for the description. None means use the default language for your agent. See IoticAgent.IOT.Config module
(xsd (vtype) – datatype): The datatype of the data you are describing, e.g. dateTime. We recommend you use a Iotic Labs-defined constant from IoticAgent.Datatypes module
description (string, optional) – The longer descriptive text for this value.
unit (ontology url, optional) – The url of the ontological description of the unit of your value. We recommend you use a constant from IoticAgent.Units module

# example with no units as time is unit-less
my_feed.create_value("timestamp",
                     Datatypes.DATETIME,
                     "en",
                     "time of reading")

# example with a unit from the Units class
my_feed.create_value("temperature",
                     Datatypes.DECIMAL,
                     "en",
                     "Fish-tank temperature in celsius",
                     Units.CELSIUS)

delete_tag(tags)¶

Delete tags for a Point 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 you want to delete from your Point, e.g. [“garden”, “soil”]

delete_value(label=None)¶

Delete the labelled value (or all values) on this Point

Raises:	`IOTException` – Infrastructure problem detected `LinkException` – Communications problem between you and the infrastructure
Parameters:	label (string, optional) – The label for the value you want to delete. If not specified, all values for this point will be removed.

foc¶: Whether this Point is a feed or control. String of either “feed” or “control”

get_meta()¶

Get the metadata object for this Point

Returns:	A IoticAgent.IOT.PointMeta module PointMeta object

OR

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

get_meta_rdf(fmt='n3')¶

Get the metadata for this Point in rdf fmt

Advanced users who want to manipulate the RDF for this Point directly without the IoticAgent.IOT.PointMeta module PointMeta)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”

lid¶: The local id of the Thing that advertises this Point. This is unique to you on this container.

list(limit=50, offset=0)¶

List all the values on this Point.

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 value details offset (integer, optional) – Return value details starting at this offset

list_followers()¶

List followers for this point, i.e. remote follows for feeds and remote attaches for controls.

Returns:	QAPI subscription list function payload

{
    "<Subscription GUID 1>": "<GUID of follower1>",
    "<Subscription GUID 2>": "<GUID of follower2>"
}

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

list_tag(limit=50, offset=0)¶

List all the tags for this Point

Returns:	List 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

pid¶: Point id - the local id of this Point. This is unique to you on this container. Think of it as a nickname for the Point

rename(new_pid)¶

Rename the Point.

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

set_meta_rdf(rdf, fmt='n3')¶: Set the metadata for this Point in rdf fmt

class IoticAgent.IOT.Point.PointDataObject(values, value_filter)¶

Bases: object

Represents a point data reading or template for filling in values, ready to be e.g. shared. NOT threadsafe.

empty¶

True if no values have been set yet.

Type:	Returns

filter_by(text=(), types=(), units=(), include_unset=False)¶: Return subset of values which match the given text, types and/or units. For a value to be matched, at least one item from each specified filter category has to apply to a value. Each of the categories must be specified as a sequence of strings. If include_unset is set, unset values will also be considered.

missing¶: List of values which do not have a value set yet

to_dict()¶: Converts the set of values into a dictionary. Unset values are excluded.

unset()¶: Unsets all values

values¶: List of all values