Tags¶
A list of tags can be found here : http://project-haystack.org/tag
For a detailed explanation of tag model, please read this: http://project-haystack.org/doc/TagModel
Pyhaystack let you find what you look for via the “find_entity” functions.
Let see how…
Finding sensors¶
Let say I want to find every sensors on a site which are temperature sensors used in zone.
op = session.find_entity(filter_expr='sensor and zone and temp')
op.wait()
This will find what you are looking for in the form of a “FindEntityOperation” object. To use the values of this object, you will need to retrive the results using
znt = op.result
Exploring points and tags¶
This will return a dict
object that contains all of the Project Haystack
entities that matched the given filter string. The entities are keyed by
identifier. When exploring interactively, you can get a list of all the
matching entities’ identifiers by calling:
list(znt.keys())
To retrieve a specific entity, you give its identifier as the key:
my_office = znt['S.SERVISYS.Salle-Conf~e9rence.ZN~2dT']
Having done this, it is possible to interrogate the tags attached to this
entity. These are accessed by the tags
property, which also returns a
pyhaystack.client.entity.tags.MutableEntityTags
if your server
supports making changes via the Project Haystack API (currently only WideSky),
or pyhaystack.client.entity.tags.ReadOnlyEntityTags
otherwise.
Both classes function like a dict
.
my_office.tags
{air, axAnnotated,
axSlotPath='slot:/Drivers/BacnetNetwork/MSTP1/PCV$2d2$2d008/points/ZN$2dT',
axStatus='ok', axType='control:NumericPoint', cur, curStatus='ok',
curVal=BasicQuantity(23.4428, '°C'),
dis='SERVISYS Salle Conférence Salle Conférence ZN-T',
equipRef=Ref('S.SERVISYS.Salle-Conf~e9rence', None, False),
his, kind='Number', navName='ZN~2dT', point,
precision=1.0, sensor, siteRef=Ref('S.SERVISYS', None, False),
temp, tz='Montreal', unit='°C', zone}
You can access specific tags, again, by giving the tag’s name as the key
val = my_office.tags['curVal']
# That will return BasicQuantity(23.4428, '°C')
# from which you can retrieve
val.value
val.unit
What is the ~nn
codes I keep seeing?¶
This is a feature specific to nHaystack. Project Haystack entity identifiers have a restricted character set, and only support a small subset of possible ASCII characters. nHaystack derives the entity’s identifier from the name supplied by the user in the back-end configuration.
To encode other forms of characters (from the ISO8859-1 character set), the
character is replaced by the sequence, ~nn
where nn
is the hexadecimal
character code for that character. In this case, you’ll see ~2d
in place
of -
, and ~e9
in place of é
.
Adding, Changing and Deleting tags¶
From this interface, it is also possible to update the values of these tags.
This requires a back-end server that supports “CRUD” operations (Create, Read,
Update & Delete). If your server supports these operations (and pyhaystack
supports using them), the tags
property will be of type
pyhaystack.client.entity.tags.MutableEntityTags
.
Again, this object functions like a dict
:
# Change the display text
znt.tags['dis'] = 'A new display text string'
# Delete the 'his' tag
del znt.tags['his']
# Add a new tag
znt.tags['space'] = hszinc.Quantity(4, 'm²')
The changes are held in memory until such time as you either commit them, or
revert them. When changes are stored locally, the is_dirty
property will
return True
.
To forget these changes and roll it back to what’s live on the server, call
revert
. This can take an optional list (or other iterable sequence) of
tag names that you specifically wish to revert.
Alternatively, to push these changes, call commit
, which takes an optional
callback function. The return value of commit
is a state machine that
returns an instance of the updated entity on success (or raises an exception
with the error):
assert znt.is_dirty # assert will pass because of changes
op = znt.commit()
op.wait()
assert op.result is znt # ← this assert will pass
assert not znt.is_dirty # assert will pass because we've "committed"
# our changes back to the server.