matlab-find-pi-assets

What it does

Find and query PI assets using MATLAB's Industrial Communication Toolbox wrappers—either direct tag lookup for PI Data Archive or AF navigation for Asset Framework hierarchies. It supports locating tags or AF elements/attributes and reading historical data when requested.

How it works

• Workflow A: Direct Tag Lookup (R2022a+)
  • Identify PI Data Archive server (must ask user; propose discovery and server selection when available).
  • Connect with piObj = piclient('serverName').
  • Search for tags with tagList = tags(piObj, Name='pattern*') using user-provided name/description.
  • Present results as a table containing a Tags column; confirm which tag to use.
  • Read data: for current value use data = read(piObj, tagName); for historical data with a range use data = read(piObj, tagName, DateRange=[start end], Interval=..., AggregateFcn=...).
• Workflow B: AF Navigation (R2026a+)
  • Identify AF server (must ask user; offer discovery and require confirmation).
  • Connect with afObj = afclient('serverName').
  • Clarify database with listDatabases(afObj) and require user confirmation to select one; connect with selectDatabase or afclient(..., Database='dbName').
  • Find elements using wildcard searches or templates; present results with Name, Template, Description, hierarchy path, and NumChildren; confirm which element to use.
  • Get attributes using getAttributes(elem, 'attributeName*'); if ambiguous, present a table with Name, ElementName, ServerDataType, DefaultUnit, HasTimeSeriesData, Description and ask user to select.
  • Validate attribute: verify parent element and, if needed, show Path for full hierarchy; warn if there is mismatch. If historical data requested but HasTimeSeriesData is false, offer to read current value instead.
  • Read data: for current value use data = read(attr); for historical data use data = readHistory(attr, startTime, endTime, Interval=hours(1), AggregateFcn="average").
  • Verify that returned data has a valid status (not all Bad or NaN).

When to use it

• You need to locate PI AF elements/attributes or PI Data Archive tags.
• You require asset hierarchies, templates, or attributes lookup, or historical data from PI AF attributes or PI tags.
• You reference PI AF servers, PI Data Archive, OSIsoft PI, AVEVA PI, or asset hierarchies.

What it can touch

• piclient, tags, read (Workflow A).
• afclient, findElementByName, getAttributes, readHistory, read (Workflow B).
• Optional: listDatabases, selectDatabase for AF navigation; server discovery patterns.

Caveats

• Requires user confirmation for server selection and database choice.
• Historical data retrieval requires HasTimeSeriesData true for attributes; otherwise current value may be read.
• Ambiguity in attributes/elements may require disambiguation via presented tables.
• Files and commands must be used exactly as stated in the tool’s documented functions (e.g., piclient, afclient, tags, read, readHistory, getAttributes, etc.).