def read_stream(self, devices=None, tag_groups=None):
"""Get a stream of device readings as plugins read from the devices.
Args:
devices (iterable[string]): An iterable which specifies the IDs of the
devices to stream reading data from.
tag_groups (iterable[tuple]): An iterable which specifies tuples containing
a set of tags to filter by. Each tag group on its own is subtractive (e.g.
all tags in the group refine the search space). The resulting set of
devices found by matching all tag groups is then collected and joined
to produce an additive set of devices to stream reading data from.
Yields:
api.V3Reading: The reading data being streamed from the targeted devices.
"""
selectors = []
if devices:
for device in devices:
selectors.append(api.V3DeviceSelector(id=device, ))
if tag_groups:
for group in tag_groups:
selectors.append(
api.V3DeviceSelector(
tags=[utils.tag_to_message(tag) for tag in group], ))
request = api.V3StreamRequest(selectors=selectors, )
try:
for reading in self.client.ReadStream(request, timeout=None):
yield reading
except Exception as e:
errors.wrap_and_raise(e)
def read(self, device_id=None, tags=None):
"""Get readings from specified plugin devices.
Args:
device_id (str): The ID of the device to get information on. If this
argument is specified, the ``tags`` argument is ignored.
tags (list[str]): The tags matching the devices to get information
on. If this is empty and ``id`` is not specified, all devices
are returned.
Yields:
api.V3Reading: The reading(s) from the specified device(s).
"""
request = api.V3ReadRequest(selector=api.V3DeviceSelector())
if device_id:
request.selector.id = device_id
elif tags:
request.selector.tags.extend(
[utils.tag_to_message(tag) for tag in tags])
try:
for reading in self.client.Read(request, timeout=self.timeout):
yield reading
except Exception as e:
errors.wrap_and_raise(e)
def devices(self, device_id=None, tags=None):
"""Get devices that the plugin manages.
Args:
device_id (str): The ID of the device to get information on. If this
argument is specified, the ``tags`` argument is ignored.
tags (list[str]): The tags matching the devices to get information
on. If this is empty and ``id`` is not specified, all devices
are returned.
Yields:
api.V3Device: The plugin-managed device(s) matching the provided
filter parameters. If no parameters are given, all devices are
returned.
"""
request = api.V3DeviceSelector()
if device_id:
request.id = device_id
elif tags:
request.tags.extend([utils.tag_to_message(tag) for tag in tags])
try:
for device in self.client.Devices(request, timeout=self.timeout):
yield device
except Exception as e:
errors.wrap_and_raise(e)
def write_async(self, device_id, data):
"""Write data to the specified plugin device. A transaction ID is returned
so the write status can be checked asynchronously.
Args:
device_id (str): The device to write to.
data (list[dict] | dict): The data to write to the device.
Yields:
api.V3WriteTransaction: The transaction(s) generated for the
asynchronous write request.
"""
request = api.V3WritePayload(
selector=api.V3DeviceSelector(id=device_id, ),
data=utils.write_data_to_messages(data),
)
try:
for txn in self.client.WriteAsync(request, timeout=self.timeout):
yield txn
except Exception as e:
errors.wrap_and_raise(e)
def write_sync(self, device_id, data):
"""Write data to the specified plugin device. This request blocks until
the write resolves so no asynchronous checking is required.
Args:
device_id (str): The device to write to.
data (list[dict] | dict): The data to write to the device.
Returns:
list[api.V3TransactionStatus]: The status of the transaction(s)
associated with the write.
"""
request = api.V3WritePayload(
selector=api.V3DeviceSelector(id=device_id, ),
data=utils.write_data_to_messages(data),
)
try:
return [
x for x in self.client.WriteSync(request, timeout=self.timeout)
]
except Exception as e:
errors.wrap_and_raise(e)
),
{
'id': '123',
'device': 'foo',
'timeout': '5s',
'context': {
'action': 'foo',
'data': b'bar',
'transaction': '',
},
},
),
(
api.V3WritePayload(
selector=api.V3DeviceSelector(
id='123',
),
),
{
'selector': {
'id': '123',
'tags': [],
},
'data': [],
},
),
(
api.V3WritePayload(
selector=api.V3DeviceSelector(
id='123',
),