matlab/matlab-find-pi-assets
> Find and query PI assets using MATLAB's Industrial Communication Toolbox. 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.
npx skills add https://github.com/matlab/matlab-agentic-toolkit --skill matlab-find-pi-assetsConnect to PI systems, locate assets, and read historical data using MATLAB's Industrial Communication Toolbox wrappers — not raw .NET SDK interop.
| 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. |
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?"
Use when the user provides a PI tag name or description.
piObj = piclient('serverName')tagList = tags(piObj, Name='pattern*') using the name or description the user providedtags() returns a table with a Tags column (string array).tagName = tagList.Tags(N), then choose based on what the user asked:data = read(piObj, tagName) — returns the snapshot/current value of the tagdata = 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.
Use when the user needs to navigate the element/attribute hierarchy.
afObj = afclient('serverName')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').results = findElementByName(afObj, 'baseIdentifier*') where baseIdentifier is the shortest identifier the user mentioned (e.g., 'GU1' from "GU1 generator")elems = findElementByTemplate(afObj, 'templateName')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 correctAlways 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.
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.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.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.data = read(attr) — returns the snapshot/current value of the attributedata = 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).
See references/key-functions.md for the full function table, attribute properties, and return types.
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.
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.
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().
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)
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)
afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
fprintf('Connected to: %s\n', afObj.ServerName);
fprintf('Database: %s\n', afObj.Database);
Use after connecting to an AF server to present databases. listDatabases returns a string array of database names (no descriptions). To show descriptions alongside names, use the .NET SDK fallback below.
afObj = afclient('myAFServer');
dbList = listDatabases(afObj);
fprintf('Available Databases on %s:\n', afObj.ServerName);
for i = 1:numel(dbList)
fprintf(' %d. %s\n', i, dbList(i));
end
To retrieve descriptions (requires .NET AFSDK):
NET.addAssembly('OSIsoft.AFSDK');
ps = OSIsoft.AF.PISystems;
afServer = ps.Item('myAFServer');
afServer.Connect();
fprintf('Available Databases on %s:\n', string(afServer.Name));
for i = 0:afServer.Databases.Count-1
db = afServer.Databases.Item(i);
dbName = string(db.Name);
desc = string(db.Description);
fprintf(' %d. %s\n', i+1, dbName);
if strlength(desc) > 0
fprintf(' Description: %s\n', desc);
end
end
afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
genUnits = findElementByTemplate(afObj, 'GenerationUnit');
disp(genUnits)
Always wildcard the base identifier to discover parent and child elements. Present results for user confirmation — even when only one element is found.
afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
results = findElementByName(afObj, 'GU1*');
fprintf('Found %d element(s) matching "GU1*":\n', numel(results));
for i = 1:numel(results)
pathParts = split(results(i).Path, '\');
hierarchy = strjoin(pathParts(4:end), '->');
fprintf(' %d. %s [Template: %s] Path: %s\n', ...
i, results(i).Name, results(i).Template, hierarchy);
if strlength(results(i).Description) > 0
fprintf(' Description: %s\n', results(i).Description);
end
end
fprintf('Which element would you like to proceed with?\n');
After the user confirms (e.g., element 2 = "GU1 Generator"), get attributes with a wildcard and show metadata:
selectedElem = results(2);
attrs = getAttributes(selectedElem, 'Active Power*');
fprintf('Matching attributes on "%s":\n', selectedElem.Name);
fprintf(' %-4s %-20s %-20s %-14s %-14s %-10s %s\n', ...
'#', 'Name', 'Element', 'ServerDataType', 'Unit', 'TimeSeries', 'Description');
for i = 1:numel(attrs)
desc = attrs(i).Description;
if strlength(desc) == 0
desc = "(none)";
end
fprintf(' %-4d %-20s %-20s %-14s %-14s %-10d %s\n', ...
i, attrs(i).Name, attrs(i).ElementName, attrs(i).ServerDataType, ...
attrs(i).DefaultUnit, attrs(i).HasTimeSeriesData, desc);
end
If only one attribute matches and it clearly corresponds to the user's request, proceed directly. If multiple attributes match or there is ambiguity (including multiple attributes with the same name from different elements), present the table above and ask the user to select. The ElementName and data type help distinguish identically-named attributes.
Note: Attribute names may differ between parent and child elements (e.g., GU1 has "Active Power Generated" while GU1 Generator has "Active Power"). A wildcard query may also return the same attribute from multiple sibling elements (e.g., all generators in a wind farm). Use the ElementName column to disambiguate.
Even when only one match is returned, present it for user confirmation before proceeding.
afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
results = findElementByName(afObj, 'GU3 Turbine*');
fprintf('Found %d element(s) matching "GU3 Turbine*":\n', numel(results));
for i = 1:numel(results)
pathParts = split(results(i).Path, '\');
hierarchy = strjoin(pathParts(4:end), '->');
fprintf(' %d. %s [Template: %s] Path: %s\n', ...
i, results(i).Name, results(i).Template, hierarchy);
end
fprintf('Proceed with this element?\n');
After confirmation:
elem = results(1);
attr = getAttributes(elem, 'Active Power');
fprintf('Name: %s\n', attr.Name);
fprintf('Unit: %s\n', attr.DefaultUnit);
fprintf('Has Time Series: %d\n', attr.HasTimeSeriesData);
Use when the user asks for the current value, snapshot, or data without specifying a time range.
afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
results = findElementByName(afObj, 'GU1*');
selectedElem = results(2);
attr = getAttributes(selectedElem, 'Active Power');
data = read(attr);
disp(data)
afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
elem = findElementByName(afObj, 'GU3 Turbine');
attr = getAttributes(elem, 'Cooling Water Output Temperature');
startTime = datetime(2025, 1, 1);
endTime = datetime(2025, 2, 1);
data = readHistory(attr, startTime, endTime, Interval=hours(1), AggregateFcn="average");
disp(data)
readHistory and read return a table with a Status column. Check for "Bad" status before using the values:
badRows = data.Status == "Bad";
if all(badRows)
warning('All returned data has "Bad" status — no valid values in this time range.');
elseif any(badRows)
fprintf('%d of %d rows have "Bad" status.\n', sum(badRows), height(data));
end
Value column types differ by source:
readHistory, read(attr)): Value is a cell array — use cell2mat(data.Value) to extract numeric values, or index with data.Value{i}read(piObj, tagName, DateRange=...)): Value is a double array (direct numeric access)read(piObj, tagName) without DateRange): Value is a string (e.g., "Pt Created" or the numeric value as text)afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
roots = getRootElements(afObj);
disp(roots)
children = getChildren(roots(1));
disp(children)
Use when the user is unsure which database contains the element they are looking for.
afObj = afclient('myAFServer');
dbList = listDatabases(afObj);
elementName = 'GU1';
foundIn = {};
for i = 1:numel(dbList)
selectDatabase(afObj, dbList(i));
results = findElementByName(afObj, elementName);
if ~isempty(results)
foundIn{end+1} = dbList(i); %#ok<SAGROW>
end
end
if isempty(foundIn)
fprintf('Element "%s" not found in any database.\n', elementName);
else
fprintf('Element "%s" found in:\n', elementName);
for i = 1:numel(foundIn)
fprintf(' %d. %s\n', i, foundIn{i});
end
end
If the element is found in multiple databases, present the list and ask the user to select the correct one. If not found in any database, ask the user to verify the element name.
afclient for Asset Framework access — never raw .NET OSIsoft.AFSDK interop (exception: server discovery via OSIsoft.AF.PISystems / OSIsoft.AF.PI.PIServers is acceptable)piclient for PI Data Archive tag access — never raw .NET interop (exception: server discovery)listDatabases returns names only)'localhost' — ask the user to specify or select from available serversfindElementByPath and findAttributeByPath path arguments — char (single-quoted) silently fails. Write findElementByPath(afObj, "\\server\db\path"), NEVER findElementByPath(afObj, '\\server\db\path')getAttributes(elem, 'name') with the name filter — never retrieve all attributes and string-comparefindElementByTemplate to find elements by type — never manually traverse the hierarchy comparing template namesfindElementByName(afObj, 'baseIdentifier*') to discover both parent and child elements — never search with an exact name onlygetChildren(elem) to show children of a specific elementread(attr) or read(piObj, tagName) (without DateRange) when the user asks for "current value", "get the data", or any request without a time range — use readHistory or read(..., DateRange=...) only when a date range is specifiedpiclient + tags when the user already knows the tag name — do not route through AF unnecessarily| Mistake | Why It's Wrong | Correct Approach |
|---------|---------------|-----------------|
| Using NET.addAssembly('OSIsoft.AFSDK') for data queries | Verbose, fragile, unnecessary — MATLAB wrappers exist | Use afclient or piclient (AFSDK is only acceptable for server discovery) |
| Using piclient for AF element queries | piclient is for PI Data Archive tags, not AF hierarchy | Use afclient for element/attribute navigation |
| Using afclient when user provides a tag name | AF navigation is overkill for direct tag lookup | Use piclient + tags(..., Name=...) |
| Assuming server is 'localhost' | Server name varies by environment | Ask the user for the server name |
| Scanning all databases without asking the user first | Resource-intensive and slow on large systems | Ask the user first; only scan all databases if user is unsure |
| Retrieving all attributes then filtering by string | Inefficient for elements with many attributes | Use getAttributes(elem, 'name') with name filter |
| Manually traversing hierarchy to find elements by template | Slow and error-prone for deep hierarchies | Use findElementByTemplate(afObj, 'templateName') |
| Picking a findElementByName result without showing it to the user | Parent and child elements often share name prefixes (e.g., GU1 vs GU1 Generator) — the first match may be the parent when the user means the child | Always wildcard search ('GU1*'), present all results with Template/Path/Description, and ask the user to confirm — even for single results |
| Proceeding to readHistory without confirming the attribute | Attribute names may differ across elements (e.g., "Active Power" vs "Active Power Generated") and wildcard may return multiple matches — or multiple sibling elements may share the same attribute name (e.g., all generators in a wind farm) | When multiple attributes match or there is ambiguity, show metadata (Name, ElementName, ServerDataType, Unit, HasTimeSeriesData, Description) and ask user to select |
| Using readHistory when user asks for current value | readHistory requires a time range — overkill for a snapshot value | Use read(attr) for AF attributes or read(piObj, tagName) without DateRange for PI tags; reserve readHistory/DateRange for historical queries |
| Using char (single-quoted) paths with findElementByPath or findAttributeByPath | These functions silently fail with char inputs — returns "Unable to find" error even when the path is correct | Always use string (double-quoted): findElementByPath(afObj, "\\server\db\path") |
| Treating listDatabases result as a struct (e.g., dbList(i).Name) | listDatabases returns a string array, not a struct — accessing .Name errors | Use dbList(i) directly: it's already a string. Pass to selectDatabase(afObj, dbList(i)) |
| Using attrs(i).DataType on attributes | Property does not exist on icomm.af.Attribute — errors at runtime | Use attrs(i).ServerDataType for the data type string |
| Using data.Value directly for math on AF results | AF readHistory/read(attr) returns Value as a cell array — arithmetic fails | Use cell2mat(data.Value) to extract numeric values from AF data |
----
Copyright 2026 The MathWorks, Inc.
----
Take matlab/matlab-find-pi-assets from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.