---

name: matlab-find-pi-assets description: > Find and query PI assets using MATLAB's Industrial Communication Toolbox. Two paths: (1) direct PI tag lookup via piclient + tags when user provides a tag name or description (R2022a+), (2) Asset Framework navigation via afclient when user needs element/attribute hierarchy (R2026a+). Use when working with PI AF servers, PI Data Archive tags, asset hierarchies, element templates, attribute lookup, or historical data from OSIsoft PI systems. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

PI Asset Identification & Data Query

Connect to PI systems, locate assets, and read historical data using MATLAB's Industrial Communication Toolbox wrappers — not raw .NET SDK interop.

Release Requirements

| Workflow | Minimum Release | Functions | |----------|----------------|-----------| | A: PI Data Archive (tag lookup) | R2022a+ | piclient, tags, read (piclient) | | B: PI Asset Framework (AF navigation) | R2026a+ | afclient, findElementByName, getAttributes, readHistory, etc. |

When to Use

• User wants to find or query PI Asset Framework elements or attributes
• User provides a PI tag name or tag description and wants to look it up
• User needs historical data from a PI AF attribute or PI tag
• User mentions PI AF server, PI Data Archive, OSIsoft, AVEVA PI, or asset hierarchy
• User wants to list elements by template (e.g., "all generation units")

When NOT to Use

• Creating or modifying AF elements/templates (administration)
• Real-time streaming, event frames, or notifications
• PI Vision or PI Web API access
• Writing data back to PI AF or PI Data Archive

Decision Logic

Choose the workflow based on what information the user provides:

| User provides | Workflow | Entry function | |---------------|----------|----------------| | A PI tag name (e.g., "GU1.ActivePower") | A: Direct Tag Lookup | piclient → tags | | A tag description or partial tag name | A: Direct Tag Lookup | piclient → tags | | An element name, template, or attribute in AF | B: AF Navigation | afclient | | A request to browse/explore the asset hierarchy | B: AF Navigation | afclient |

If unclear, ask the user: "Do you have a specific PI tag name, or do you need to navigate the Asset Framework hierarchy?"

Workflow A: Direct Tag Lookup (R2022a+)

Use when the user provides a PI tag name or description.

1. Identify PI Data Archive server (MUST ask user) — If the user has not specified a server name, run the PI server discovery pattern (see Discover Available PI Data Archive Servers) to enumerate available servers. If no servers are found, inform the user that no PI Data Archive servers are discoverable on the host machine and ask them to provide the server name manually. If servers are found, you MUST present the list to the user and ask them to select a server — never auto-select or assume which server to use. Include descriptions (if available) and a "None of these" option. If the user selects "None of these", ask them to provide the server name manually. Do not proceed to the next step until the user has confirmed a server.

2. Connect — piObj = piclient('serverName')

3. Search for tags — tagList = tags(piObj, Name='pattern*') using the name or description the user provided

4. Present results — Show the matching tags to the user for confirmation. tags() returns a table with a Tags column (string array).

5. Read data — Extract the tag name with tagName = tagList.Tags(N), then choose based on what the user asked:

   • Current value or no time range specified: data = read(piObj, tagName) — returns the snapshot/current value of the tag
   • Historical data with time range: data = read(piObj, tagName, DateRange=[start end], Interval=..., AggregateFcn=...)

   If the user says "get the value", "what is the current reading", or requests data without specifying a date range, use read(piObj, tagName) without DateRange.

Workflow B: Asset Framework Navigation (R2026a+)

Use when the user needs to navigate the element/attribute hierarchy.

1. Identify AF server (MUST ask user) — If the user has not specified a server name, run the AF server discovery pattern (see Discover Available AF Servers) to enumerate available servers. If no servers are found, inform the user that no AF servers are discoverable on the host machine and ask them to provide the server name manually. If servers are found, you MUST present the list to the user and ask them to select a server — never auto-select or assume which server to use. Include descriptions (if available) and a "None of these" option. If the user selects "None of these", ask them to provide the server name manually. Do not proceed to the next step until the user has confirmed a server.

2. Connect — afObj = afclient('serverName')

3. Clarify database (MUST ask user) — Use listDatabases(afObj) to show available databases and you MUST ask the user to select one — never auto-select or assume which database to use, even if only one database exists. listDatabases returns a string array of names only — to show descriptions alongside names, use the .NET SDK fallback (see List Databases with Descriptions). If the user is unsure which database contains their element, run the cross-database search pattern (see Search for Element Across All Databases) to find the correct database. Do not proceed to the next step until the user has confirmed a database. Once identified, connect with selectDatabase(afObj, dbList(N)) or afObj = afclient('serverName', Database='dbName').

4. Find elements with disambiguation — Always use a wildcard search to discover related elements:

   • Search: results = findElementByName(afObj, 'baseIdentifier*') where baseIdentifier is the shortest identifier the user mentioned (e.g., 'GU1' from "GU1 generator")
   • By template (if searching by type): elems = findElementByTemplate(afObj, 'templateName')
   • By path (when full path is known): elem = findElementByPath(afObj, "\\server\database\path\to\element") — MUST use string (double-quoted), NEVER char (single-quoted) — char input silently fails and returns an error even when the path is correct

   Always present results for user confirmation: Regardless of how many elements are returned, present a table to the user showing Name, Template, Description, hierarchy path using arrow notation (e.g., Flynn River Hydro->Flynn I->GU1->GU1 Generator — strip \\server\database\ prefix and join with ->), and NumChildren. Ask the user to confirm which element they mean. If the user asks for more detail, use getChildren or getAttributes on a specific element to help them navigate. Only proceed once the user confirms.

5. Get attributes and confirm — Use getAttributes(elem, 'attributeName*') with a wildcard name filter. If only one attribute matches and it clearly corresponds to the user's request, proceed directly. Important If multiple attributes match or there is ambiguity (e.g., "Active Power" vs "Active Power Generated", or multiple attributes with the same name from different elements), present the matching attributes in a table showing Name, ElementName, ServerDataType, DefaultUnit, HasTimeSeriesData, and Description — then ask the user to select the correct one(s). The element name and data type help the user distinguish between identically-named attributes on different elements.

6. Validate attribute — After the user confirms an attribute, perform these checks before reading data:

   • Verify parent element: Confirm attr.ElementName matches the user's intended asset. For full hierarchy verification, use attr.Path (format: \\server\database\...\element|attribute) — when displaying to the user, strip the \\server\database\ prefix and join with -> (e.g., Flynn River Hydro->Flynn I->GU1->GU1 Generator|Active Power). If the element suggests a different asset than what the user asked for (e.g., a similarly-named attribute on a sibling element), flag this to the user before proceeding.
   • Check time series availability: If the user requested historical/range-based data and HasTimeSeriesData is false, inform the user that the selected attribute does not contain time series data and ask whether they would still like to proceed with reading the current value instead.

7. Read data — Choose based on what the user asked:

   • Current value or no time range specified: data = read(attr) — returns the snapshot/current value of the attribute
   • Historical data with time range: data = readHistory(attr, startTime, endTime, Interval=hours(1), AggregateFcn="average")

   If the user says "get the value", "what is the current reading", or requests data without specifying a date range, use read(attr).

8. Verify — Check that returned data has valid status (not all "Bad" or NaN)

Key Functions

See references/key-functions.md for the full function table, attribute properties, and return types.

Patterns

Discover Available AF Servers

NET.addAssembly('OSIsoft.AFSDK');
ps = OSIsoft.AF.PISystems;
numServers = ps.Count;
if numServers == 0
    fprintf('No AF servers discovered on this machine.\n');
else
    fprintf('Available AF Servers:\n');
    for i = 0:numServers-1
        serverName = string(ps.Item(i).Name);
        desc = string(ps.Item(i).Description);
        fprintf('  %d. %s\n', i+1, serverName);
        if strlength(desc) > 0
            fprintf('     Description: %s\n', desc);
        end
    end
end

If numServers == 0, ask the user to provide the AF server name manually — no servers are discoverable on the host machine.

Discover Available PI Data Archive Servers

NET.addAssembly('OSIsoft.AFSDK');
piServers = OSIsoft.AF.PI.PIServers;
numServers = piServers.Count;
if numServers == 0
    fprintf('No PI Data Archive servers discovered on this machine.\n');
else
    fprintf('Available PI Data Archive Servers:\n');
    for i = 0:numServers-1
        serverName = string(piServers.Item(i).Name);
        desc = string(piServers.Item(i).Description);
        fprintf('  %d. %s\n', i+1, serverName);
        if strlength(desc) > 0
            fprintf('     Description: %s\n', desc);
        end
    end
end

If numServers == 0, ask the user to provide the PI Data Archive server name manually — no servers are discoverable on the host machine.

Direct Tag Lookup by Name

piObj = piclient('myPIServer');
tagList = tags(piObj, Name='GU1*');
disp(tagList)

tags() returns a table with a Tags column (string array). Extract a tag name with tagList.Tags(N) before passing to read().

Read Current Value from PI Tag

Use when the user asks for the current/snapshot value of a PI tag without specifying a time range.

piObj = piclient('myPIServer');
tagList = tags(piObj, Name='GU1.Active Power*');
tagName = tagList.Tags(1);
data = read(piObj, tagName);
disp(data)

Read Historical Data from PI Tag

piObj = piclient('myPIServer');
tagList = tags(piObj, Name='GU1.Active Power*');
tagName = tagList.Tags(1);
startTime = datetime(2025, 1, 1);
endTime = datetime(2025, 2, 1);
data = read(piObj, tagName, DateRange=[startTime endTime], ...
    Interval=hours(1), AggregateFcn="average");
disp(data)

AF Connection with Server and Database Clarification

afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
fprintf('Connected to: %s\n', afObj.ServerName);
fprintf('Database: %s\n', afObj.Database);

List Databases with Descriptions

Use after connecting to an AF server