PI Adapter for MQTT

© Copyright 1995- 2022

OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577
All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in
any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written
permission of OSIsoft, LLC.

OSIsoft, the OSIsoft logo and logotype, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services, OSIsoft
Connected Services, OSIsoft EDS, PI ACE, PI Advanced Computing Engine, PI AF SDK, PI API, PI Asset
Framework, PI Audit Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Data Archive, PI DataLink, PI
DataLink Server, PI Developers Club, PI Integrator for Business Analytics, PI Interfaces, PI JDBC Driver, PI Manual
Logger, PI Notifications, PI ODBC Driver, PI OLEDB Enterprise, PI OLEDB Provider, PI OPC DA Server, PI OPC HDA
Server, PI ProcessBook, PI SDK, PI Server, PI Square, PI System, PI System Access, PI Vision, PI Visualization Suite,
PI Web API, PI WebParts, PI Web Services, RLINK and RtReports are all trademarks of OSIsoft, LLC.

All other trademarks or trade names used herein are the property of their respective owners.

U.S. GOVERNMENT RIGHTS

Use, duplication or disclosure by the US Government is subject to restrictions set forth in the OSIsoft, LLC license
agreement and/or as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12-212, FAR 52.227-19, or their
successors, as applicable.

ii PI Adapter for MQTT Published: 19 July 2022

 Contents

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Principles of operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Text parser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
JSONPath syntax for value retrieval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
System requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Install the adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Installation using Docker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Upgrade the adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Uninstall the adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Configuration tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
System components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
System and adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Data source (generic). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Data source (Sparkplug B). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Client settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Data source discovery (generic). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Data source discovery (Sparkplug B). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Data selection (generic). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Data selection (Sparkplug B). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Data filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Diagnostics and metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Buffering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Egress endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Prepare egress destinations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Configure a network proxy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Health endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Configuration examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Start and stop an adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Start and stop ingress component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Delete an adapter component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Retrieve product version information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Health and Diagnostics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Health. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Device status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

3 iii
 Next health message expected. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Diagnostics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Stream count. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
IO rate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Error rate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Egress. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Troubleshoot PI Adapter for MQTT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Release notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Technical support and feedback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

iv PI Adapter for MQTT Published: 19 July 2022

 Overview
PI Adapter for MQTT is a data-collection component that transfers time-series data from source devices to
OMF endpoints in OSIsoft Cloud Services or PI Servers. MQTT (Message Queuing Telemetry Transport) is a
messaging protocol created for Machine-to-Machine (M2M)/Internet of Things (IOT) communication. The
adapter can connect to any device that uses the MQTT protocol for communication with constrained
devices and server applications for data exchange.

Adapter installation
You can install the adapter with a download kit that you can obtain from the OSIsoft Customer Portal. You
can install the adapter on devices running either Windows or Linux operating systems.

Adapter configuration
Using REST API, you can configure all functions of the adapter. The configurations are stored in JSON files.
For data ingress, you must define an adapter component in the system components configuration for each
device to which the adapter will connect. You configure each adapter component with the connection
information for the device and the data to collect. For data egress, you must specify destinations for the
data, including security for the outgoing connection. Additional configurations are available to egress health

1 PI Adapter for MQTT Published: 19 July 2022

 and diagnostics data, add buffering configuration to protect against data loss, and record logging
information for troubleshooting purposes.

Once you have configured the adapter and it is sending data, you can use administration functions to
manage the adapter or individual ingress components of the adapter. Health and diagnostics functions
monitor the status of connected devices, adapter system functions, the number of active data streams, the
rate of data ingress, the rate of errors, and the rate of data egress.

EdgeCmd utility
OSIsoft also provides the EdgeCmd utility, a proprietary command line tool to configure and administer an
adapter on both Linux and Windows operating systems. EdgeCmd utility is installed separately from the
adapter.

2 PI Adapter for MQTT Published: 19 July 2022

 Principles of operation
This adapter's operations focus on data collection and stream creation.

Adapter configuration
To start data collection for the MQTT adapter, configure the following:

• Data source: Provide the data source from which the adapter should collect data.
For more details, see the data source topics PI Adapter for MQTT data source configuration and PI
Adapter for MQTT Sparkplug B data source configuration.

• Data selection: Select MQTT items to which the adapter should subscribe for data.
For more details, see the data selection topics PI Adapter for MQTT data selection configuration and
PI Adapter for MQTT Sparkplug B data selection configuration.

• Logging: Set up the logging attributes to manage the adapter logging behavior.

Connection
The adapter uses either the Transmission Control Protocol (TCP) or WebSocket protocol (WS) to speak to an
MQTT server. For more information on how to configure which protocol should be used, see PI Adapter for
MQTT data source configuration and PI Adapter for MQTT Sparkplug B data source configuration.

Data collection
The adapter collects time-series data from the MQTT server using Topics. The generic MQTT adapter only
supports data from devices producing JSON payload, the MQTT Sparkplug B adapter also supports data
from devices adhering to the Sparkplug B specification. For more information see PI Adapter for MQTT data
selection configuration and PI Adapter for MQTT Sparkplug B data selection configuration.

Data types
The following sections list both MQTT generic and MQTT Sparkplug B data types and their respective
stream data types.

MQTT data types

The following table lists MQTT variable types that the adapter collects data from and the types of streams
that will be created.

MQTT data type Stream data type

Int16 Int16

Int32 Int32

Int64 Int64

3 PI Adapter for MQTT Published: 19 July 2022

 MQTT data type Stream data type

UInt16 UInt16

UInt32 UInt32

UInt64 UInt64

Float32 Float32

Float64 Float64

Boolean Boolean

String String

Date-Time Date-Time

The following table lists MQTT complex types that the adapter collects data from and the type of streams
that will be created.

MQTT complex type Stream data type

Geolocation Float32

Coordinates Float32

MQTT Sparkplug B data types

The following table lists MQTT Sparkplug B variable types that the adapter collects data from and the types
of streams that will be created.

MQTT Sparkplug B data type Stream data type

Int8 Int8

Int16 Int16

Int32 Int32

Int64 Int64

UInt8 UInt8

UInt16 UInt16

UInt32 UInt32

UInt64 UInt64

4 PI Adapter for MQTT Published: 19 July 2022

 MQTT Sparkplug B data type Stream data type

Float Float32

Double Float64

Boolean Boolean

String String

DateTime UInt64

Text String

Stream creation
The MQTT adapter creates a stream with two properties for each selected MQTT item. The properties are
described in the following table.

Property name Data type Description

Timestamp String The response time of the stream data from the MQTT device

Value Specified by the data selection The value of the stream data from the MQTT device

Certain metadata are sent with each stream created. The following metadata are common for every adapter
type:

• ComponentId: Specifies the data source, for example, MQTT1

• ComponentType: Specifies the type of adapter, for example, MQTT

MQTT specific metadata

Metadata specific to the MQTT generic component are:

• Topic: Specifies the MQTT topic string

• ValueField: Specifies the JsonPath expression used to extract the data value from a property within
the payload supplied by the MQTT server

Note: A configured metadata level allows you to set the amount of metadata for the adapter. Specify the
metadata level in General configuration. For the MQTT adapter, the following metadata are sent for the
individual level:

• None: No metadata

• Low: AdapterType (ComponentType) and DataSource (ComponentId)

5 PI Adapter for MQTT Published: 19 July 2022

 • Medium: AdapterType (ComponentType), DataSource (ComponentId), Topic, and ValueField or
DataFields

Each stream created for the selected measurement has a unique identifier (stream Id). If you specify a
custom stream Id for the measurement in the data selection configuration, the adapter uses that stream Id
to create the stream. Otherwise, the adapter constructs the stream Id using the following format:

<AdapterComponentId>.<Topic>.<ValueField>

Note: StreamIdPrefix and DefaultStreamIdPattern settings in the data source configuration

affect the naming convention. For more information, see PI Adapter for MQTT data source configuration.

MQTT Sparkplug B specific metadata

Metadata specific to the MQTT Sparkplug B component are:

• Namespace: Specifies the topic namespace

• Group_Id: Specifies the element of the topic namespace that logically groups MQTT EoN1 nodes into
the MQTT server and the consuming MQTT clients

• Edge_Node_Id: Specifies the element of the topic namespace that uniquely identifies the MQTT
EoN1 node within the infrastructure

• Device_Id: Specifies the element of the topic namespace that identifies a device attached to the
MQTT EoN1 node

1 EoN = Edge of Network

Note: A configured metadata level allows you to set the amount of metadata for the adapter. Specify the
metadata level in General configuration. For the MQTT adapter, the following metadata are sent for the
individual level:

• None: No metadata

• Low: AdapterType (ComponentType) and DataSource (ComponentId)

• Medium: AdapterType (ComponentType), DataSource (ComponentId), Topic, and MetricName

Each stream created for the selected measurement has a unique identifier (stream Id). If you specify a
custom stream Id for the measurement in the data selection configuration, the adapter uses that stream Id
to create the stream. Otherwise, the adapter constructs the stream Id using the following format:

<AdapterComponentId>.<BaseTopic>.<MetricName>

6 PI Adapter for MQTT Published: 19 July 2022

 Note: StreamIdPrefix and DefaultStreamIdPattern settings in the data source configuration
affect the naming convention. For more information, see PI Adapter for MQTT Sparkplug B data source
configuration.

Text parser
PI Adapter for MQTT includes the text parser component which ensures consistent parsing of text from
different files. This adapter supports parsing of .json files.

Designed to be a document parser, the text parser parses a semantically complete document in its entirety.
The text parser produces OMF compatible output, which in turn is compatible with the OCS backing SDS
(Sequential Data Store) that stores data in streams consisting of multiple values and indexes.

Data types supported by the text parser

The following data types are supported by the text parser:

• DateTime

• DateTimeOffset

• TimeSpan

• sbyte

• byte

• short

• ushort

• int

• uint

• long

• ulong

• float

• double

• decimal

• bool

• char

7 PI Adapter for MQTT Published: 19 July 2022

 • string

Note: Not all data types supported by the text parser are also supported by OMF.

Special characters support

As part of the default StreamId logic, the text parser replaces special characters as follows:

Special character Replacement character

* empty string

' empty string

` empty string

" empty string

? empty string

; -

\| -

\ -

{ (

} )

[ (

] )

Culture support
Some numeric values and datetimes support cultures when they are being parsed. The default culture is
en-US (US English) (InvariantCulture). OSIsoft recommends that you leave the adapter at the default
unless you expect culturally variant input.

Note: Installed cultures vary by machine with both Linux and Windows. If the specified culture is not
installed, the text parser fails to parse input that requires that culture.

Time zone support

A time zone or offset specified by a time is always used to convert to UTC time. Time zones are only used if
there is no offset or time zone specifier in a text date and time string.

8 PI Adapter for MQTT Published: 19 July 2022

 For time zones that support time changes between daylight and standard times, a text file may temporarily
contain invalid or ambiguous datetimes during the time change, which are possible only for a two-hour
period each year. When these time changes occur, the text parser logs them, but the datetime is parsed and
passed to the callback. Ambiguous times are reported as standard times, which is the Microsoft
recommendation.

Date and time processing

The text parser can use time zones, cultures, and custom formats to read dates and times from ingress data.

You can specify date and time formats when you configure data selection. Set the date and time using the
IndexFormat property. If you leave the IndexFormat property unset, the data selection configuration
defaults to the ISO 8601 date format.

If you are using a culture other than default en-US, use the name of day or month specific to the culture.
For example, use "Juni" instead of "June" for the de-DE culture.

The following date and time syntaxes have been tested and are supported.

"MM/dd/yyyy H:mm:ss zzz" "06/15/2018 15:15:30 -05:00"

"MM/dd/yyyy H:mm:ss.fff zzz" "06/15/2018 15:15:30.123 -05:00"
"dd/MM/yyyy H:mm:ss.fff K" "15/06/2018 15:15:30.123 Z"
"MMMM/dd/yyyy H:mm:ss.fff K" "June/15/2018 15:15:30.123 Z" (InvariantCulture/English)
"MMMM/dd/yyyy H:mm:ss.fff K" "Juni/15/2018 15:15:30.123 Z" (German)
"MMM/dd/yyyy H:mm:ss.fff K" "Jun/15/2018 15:15:30.123 Z"
"MMM-dd-yyyy H:mm:ss.fff K" "Jun-15-2018 15:15:30.123 Z"
"MMM-dd-yyyy H:mm:ss.fff K" "Jun-15-2018 15:15:30.123 Z"
"MMM-dd-yyyy H:mm:ss.fff K" "Jun-15-2018 15:15:30.123 Z"
"yyyy-MM-dd H:mm:ss.fff K" "2018-06-15 15:15:30.123 Z"
"yyyy-M-d H:mm:ss.fff K" "2018-6-5 15:15:30.123 Z"
"yyyy-M-d H:mm:ss.fff zzz" "2018-6-5 15:15:30.123 +05:00"
"ddd dd MMM yyyy h:mm tt zzz" "Sun 15 Jun 2008 8:30 AM -06:00"
"dddd dd MMM yyyy h:mm tt zzz" "Sunday 15 Jun 2008 8:30 AM -06:00"
"dddd dd MMM yyyy h:mm tt zzz" "Sunday 15 Jun 2008 8:30 AM -06:00"
"dddd dd MMMM yyyy h:mm tt zzz" "Sunday 15 June 2008 8:30 AM -06:00"

Adapter date and time processing uses Microsoft datetime parsing.

• For more documentation on standard datetime formats, which fit most use cases, see Standard date
and time format strings.

9 PI Adapter for MQTT Published: 19 July 2022

 • For documentation on custom datetime formation, see Custom date and time format strings.

JSONPath syntax for value retrieval

For information on which semantic is used for retrieving values from JSON files, see JSONPath Syntax.

The following syntax is used to extract values from JSON documents.

JSON - Simple JSONPath example

[
{
"time": "2020-08-10T12:10:46.0928791Z",
"value": 1.234567890
},
{
"time": "2020-08-10T12:10:47.0928791Z",
"value": 12.34567890
},
{
"time": "2020-08-10T12:10:48.0928791Z",
"value": 123.4567890
},
{
"time": "2020-08-10T12:10:49.0928791Z",
"value": 1234.567890
},
{
"time": "2020-08-10T12:10:50.0928791Z",
"value": 12345.67890
},
{
"time": "2020-08-10T12:10:51.0928791Z",
"value": 123456.7890
},
{
"time": "2020-08-10T12:10:52.0928791Z",
"value": 12345678.90
},
{

10 PI Adapter for MQTT Published: 19 July 2022

 "time": "2020-08-10T12:10:53.0928791Z",
"value": 123456789.0
}
]

The following MQTT data selection configuration reads a series of values. The configuration assumes that
the JSON was sent to MQTT Topic "Test":

[
{
"Topic": "Test",
"ValueField": "$.[*].value",
"DataFields": null,
"IndexField": "$.[*].time",
"DataType": "float64",
"IndexFormat": null,
"Selected": true,
"Name": null,
"StreamId": "TestValues",
"DataFilterId": null
}
]

JSON - Complex JSONPath examples

The following example reads specific values from a JSON array:

{
"StreamData": {
"TPPrototype.uflsample.value_time": [
{
"StreamId": "TPPrototype.uflsample.value_time",
"DataType": "Double",
"Timestamp": "2013-12-01T06:00:00Z",
"Value": 339.0
},
{
"StreamId": "TPPrototype.uflsample.value_time",
"DataType": "Double",

11 PI Adapter for MQTT Published: 19 July 2022

 "Timestamp": "2013-12-01T07:00:00Z",
"Value": 344.0
},
{
"StreamId": "TPPrototype.uflsample.value_time",
"DataType": "Double",
"Timestamp": "2013-12-01T17:00:00Z",
"Value": 341.0
}
],
"TPPrototype.uflsample.value_timeString": [
{
"StreamId": "TPPrototype.uflsample.value_timeString",
"DataType": "String",
"Timestamp": "2013-12-01T06:00:00Z",
"Value": "339.0"
},
{
"StreamId": "TPPrototype.uflsample.value_timeString",
"DataType": "String",
"Timestamp": "2013-12-01T07:00:00Z",
"Value": "344.0"
},
{
"StreamId": "TPPrototype.uflsample.value_timeString",
"DataType": "String",
"Timestamp": "2013-12-01T17:00:00Z",
"Value": "341.0"
}
],
"TPPrototype.uflsample.pressure_time": [
{
"StreamId": "TPPrototype.uflsample.pressure_time",
"DataType": "Double",
"Timestamp": "2013-12-01T06:00:00Z",
"Value": 339.0
},
{
"StreamId": "TPPrototype.uflsample.pressure_time",
"DataType": "Double",
"Timestamp": "2013-12-01T07:00:00Z",

12 PI Adapter for MQTT Published: 19 July 2022

 "Value": 344.0
},
{
"StreamId": "TPPrototype.uflsample.pressure_time",
"DataType": "Double",
"Timestamp": "2013-12-01T17:00:00Z",
"Value": 341.0
}
]
}
}

The following MQTT data selection configuration reads all the

TPPrototype.uflsample.value_time values from the JSON above. The configuration assumes
that the JSON was sent to MQTT Topic "Test":

[
{
"Topic": "Test",
"ValueField": "$['StreamData'].['TPPrototype.uflsample.value_time'][*].Value",
"DataFields": null,
"IndexField": "$['StreamData'].['TPPrototype.uflsample.value_time'][*].Timestamp",
"DataType": "float64",
"IndexFormat": null,
"Selected": true,
"Name": null,
"StreamId": "TestPrototypeValues",
"DataFilterId": null
}
]

The following example reads specific values from a complex nested JSON:

{
"success": true,
"error": null,
"result": {
"type": "runtime_history",
"chart": {

13 PI Adapter for MQTT Published: 19 July 2022

 "chart": {
"type": "column"
},
"title": {
"text": ""
},
"subtitle": {
"text": "Daily History"
},
"colors": [
"#fee292",
"#fdc152",
"#f69638",
"#f17130",
"#9f2d26",
"#8acadc",
"#184c8e"
],
"series": [
{
"name": "Stage 3 Aux Heat",
"data": [
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"stack": "heat",
"state": "heat_aux_stage3"
},
{
"name": "Stage 2 Aux Heat",
"data": [
0.0,
0.0,
0.0,

14 PI Adapter for MQTT Published: 19 July 2022

 0.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"stack": "heat",
"state": "heat_aux_stage2"
},
{
"name": "Aux Heat",
"data": [
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"stack": "heat",
"state": "heat_aux"
},
{
"name": "Stage 2 Heat",
"data": [
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"stack": "heat",
"state": "heat_stage2"

15 PI Adapter for MQTT Published: 19 July 2022

 },
{
"name": "Heat",
"data": [
0.0,
0.2,
0.0,
0.0,
0.0,
0.0,
0.3,
0.2,
0.0
],
"stack": "heat",
"state": "heat"
},
{
"name": "Stage 2 Cool",
"data": [
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"stack": "cool",
"state": "cool_stage2"
},
{
"name": "Cool",
"data": [
0.0,
0.0,
0.0,
0.0,
0.0,

16 PI Adapter for MQTT Published: 19 July 2022

 0.0,
0.0,
0.0,
0.0
],
"stack": "cool",
"state": "cool"
}
],
"xAxis": {
"categories": [
"Friday",
"Saturday",
"Sunday",
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday",
"Saturday"
],
"labels": {
"rotation": -45
}
},
"yAxis": {
"allowDecimals": false,
"min": 0,
"max": 24,
"tickInternval": 4,
"title": {
"text": "Runtime (Hours)"
}
},
"legend": {
"layout": "vertical",
"align": "center",
"floating": false,
"shadow": false,
"itemStyle": {
"fontSize": "1em"

17 PI Adapter for MQTT Published: 19 July 2022

 }
},
"tooltip": {
"shared": true,
"borderColor": "#000000"
},
"credits": {
"enabled": false
},
"plotOptions": {
"column": {
"stacking": "normal"
},
"series": {
"shadow": false
}
}
},
"table": {
"headings": [
"Fri",
"Sat",
"Sun",
"Mon",
"Tue",
"Wed",
"Thu",
"Fri",
"Sat"
],
"series": [
{
"name": "Aux Heat",
"data": [
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,

18 PI Adapter for MQTT Published: 19 July 2022

 0.0,
0.0
],
"stack": "heat",
"state": "heat_aux"
},
{
"name": "Outdoor High Temp.",
"data": [
72.0,
64.0,
73.0,
72.0,
67.0,
73.0,
77.0,
62.0,
51.0
],
"stack": null,
"state": "outdoor_high_temperature"
},
{
"name": "Outdoor Low Temp.",
"data": [
55.0,
60.0,
62.0,
61.0,
51.0,
43.0,
46.0,
44.0,
35.0
],
"stack": null,
"state": "outdoor_low_temperature"
},
{
"name": "Avg Indoor Temp.",
"data": [

19 PI Adapter for MQTT Published: 19 July 2022

 76.0,
77.0,
78.0,
78.0,
77.0,
73.0,
74.0,
75.0,
72.0
],
"stack": null,
"state": "average_indoor_temperature"
},
{
"name": "Avg Indoor Humidity",
"data": [
66.0,
68.0,
70.0,
70.0,
69.0,
67.0,
67.0,
66.0,
61.0
],
"stack": null,
"state": "average_indoor_humidity"
},
{
"name": "Fan Only Runtime",
"data": [
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0

20 PI Adapter for MQTT Published: 19 July 2022

 ],
"stack": null,
"state": "fan_only"
},
{
"name": "Vent",
"data": [],
"stack": null,
"state": "vent"
}
]
},
"show_monthly_runtime_history": true
}
}

The following MQTT data selection configuration reads Sunday Average Indoor Temperature.
The timestamp is the Adapter local time. The configuration assumes that the JSON was sent to MQTT Topic
"Test":

[
{
"Topic": "Test",
"ValueField": "$.result.table.series[3].data[2]",
"DataFields": null,
"IndexField": null,
"DataType": "float64",
"IndexFormat": null,
"Selected": true,
"Name": null,
"StreamId": "TestSundayTemperature",
"DataFilterId": null
}
]

Error handling
If you encounter text parser related errors that is errors for the ValueField or IndexField, check the
StreamId associated with the error message.

21 PI Adapter for MQTT Published: 19 July 2022

 Possible errors include the following:

• The JSONPath expression of ValueField or IndexField is pointing to a non-existing value

• The JSONPath expression of ValueField or IndexField is missing a value altogether

• DataType does not match the value

Additional help
PI Adapter for MQTT's discovery feature helps you find collectible data without manually creating the data
selection file. For information on discovery, see Data source discovery generic.

22 PI Adapter for MQTT Published: 19 July 2022

 Installation
Adapters are installed on a local machine using an install kit downloaded from the OSIsoft Customer Portal.
For instructions on downloading and installing adapters, see Install the adapter.

Alternatively, you can build custom installers or containers for Linux. For more information, see the Docker
instructions in the documentation of the respective adapter.

23 PI Adapter for MQTT Published: 19 July 2022

 System requirements
PI Adapter for MQTT is supported on a variety of platforms and processors. Install kits are available for the
following platforms:

Operating System Platform Installation Kit Processor(s)

Windows 10 Enterprise x64 PI-Adapter-for- Intel/AMD 64-bit

Windows 10 IoT Enterprise MQTT_1.0.0.167-x64_.msi processors

Debian 9, 10 x64 PI-Adapter-for- Intel/AMD 64-bit

Ubuntu 18.04, 20.04 MQTT_1.0.0.167-x64_.deb processors

Debian 9, 10 ARM32 PI-Adapter-for- ARM 32-bit processors

Ubuntu 20.04 MQTT_1.0.0.167-arm_.deb

Debian 10 ARM64 PI-Adapter-for- ARM 64-bit processors

Ubuntu 20.04 MQTT_1.0.0.167-arm64_.deb

Alternatively, you can use tar.gz files with binaries to build your own custom installers or containers for
Linux. For more information on installing the adapter with Docker containers, see Installation using Docker.

PI Web API compatibility

This version of PI Adapter for MQTT is compatible with PI Web API 2021 and later.

Install the adapter

You can install adapters on either a Windows or Linux operating system. Before installing the adapter, see
the respective system requirements to ensure your machine is properly configured to provide optimum
adapter operation.

Windows
Complete the following steps to install a PI adapter on a Windows computer:

1. Download PI-Adapter-for-MQTT_1.0.0.167-x64_.msi from the OSIsoft Customer portal.

Note: Customer login credentials are required to access the portal.

2. Run PI-Adapter-for-MQTT_1.0.0.167-x64_.msi file.

3. Follow the setup wizard.

24 PI Adapter for MQTT Published: 19 July 2022

 You can change the installation folder or port number during setup. The default port number is 5590.

4. Optional: To verify the installation, run the following curl command with the port number that you
specified during installation:

curl http://localhost:5590/api/v1/configuration

If you receive an error, wait a few seconds and try the script again. If the installation was successful, a
JSON copy of the default system configuration is returned.

Linux
Complete the following steps to install an adapter on a Linux computer:

1. Download the appropriate Linux distribution file (PI-Adapter-for-MQTT_1.0.0.167-

platform_.deb) from the OSIsoft Customer portal.

Note: Customer login credentials are required to access the portal.

2. Open a terminal.

3. Run the sudo apt update command to update available packages information.

4. Run the sudo apt install command against the Linux distribution file (PI-Adapter-for-
MQTT_1.0.0.167-platform_.deb) selected in step 1 of this procedure.

For example: sudo apt install ./PI-Adapter-for-MQTT_1.0.0.167-x64_.deb

5. Optional: To verify the installation, run the following curl command with the port number that you
specified during installation:

curl http://localhost:5590/api/v1/configuration

If you receive an error, wait a few seconds and run the command again. If the installation was
successful, a JSON copy of the default system configuration is returned.

Installation using Docker

Docker is a set of tools that you can use on Linux to manage application deployments. This topic provides
examples of how to create a Docker container with the adapter.

Notes:

25 PI Adapter for MQTT Published: 19 July 2022

 • The use of Docker is only recommended if your environment requires it. Only users proficient with
Docker should use it to install the adapter. Docker is not required to use the adapter.

• Running adapters in Docker containers on Windows is not supported.

Create a startup script

To create a startup script for the adapter, follow the instructions below.

1. Use a text editor to create a script similar to one of the following examples:

Note: The script varies slightly by processor.

ARM32

#!/bin/sh
if [ -z $portnum ] ; then
exec /PI-Adapter-for-MQTT_1.0.0.167-arm_/OSIsoft.Data.System.Host
else
exec /PI-Adapter-for-MQTT_1.0.0.167-arm_/OSIsoft.Data.System.Host --port:$portnum
fi

ARM64

#!/bin/sh
if [ -z $portnum ] ; then
exec /PI-Adapter-for-MQTT_1.0.0.167-arm64_/OSIsoft.Data.System.Host
else
exec /PI-Adapter-for-MQTT_1.0.0.167-arm64_/OSIsoft.Data.System.Host --port:$portnum
fi

AMD64

#!/bin/sh
if [ -z $portnum ] ; then
exec /PI-Adapter-for-MQTT_1.0.0.167-x64_/OSIsoft.Data.System.Host
else
exec /PI-Adapter-for-MQTT_1.0.0.167-x64_/OSIsoft.Data.System.Host --port:$portnum
fi

26 PI Adapter for MQTT Published: 19 July 2022

 2. Name the script mqttdockerstart.sh and save it to the directory where you plan to create the
container.

Create a Docker container

To create a Docker container that runs the adapter, follow the instructions below.

1. Create the following Dockerfile in the directory where you want to create and run the container.

Note: Dockerfile is the required name of the file. Use the variation according to your operating
system:

ARM32

FROM ubuntu:20.04
WORKDIR /
RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y ca-certificates li
bicu60 libssl1.1 curl
COPY mqttdockerstart.sh /
RUN chmod +x /mqttdockerstart.sh
ADD ./PI-Adapter-for-MQTT_1.0.0.167-arm_.tar.gz .
ENTRYPOINT ["/mqttdockerstart.sh"]

ARM64

FROM ubuntu:20.04
WORKDIR /
RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y ca-certificates li
bicu66 libssl1.1 curl
COPY mqttdockerstart.sh /
RUN chmod +x /mqttdockerstart.sh
ADD ./PI-Adapter-for-MQTT_1.0.0.167-arm64_.tar.gz .
ENTRYPOINT ["/mqttdockerstart.sh"]

AMD64 (x64)

FROM ubuntu:20.04
WORKDIR /
RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y ca-certificates li
bicu66 libssl1.1 curl

27 PI Adapter for MQTT Published: 19 July 2022

 COPY mqttdockerstart.sh /
RUN chmod +x /mqttdockerstart.sh
ADD ./PI-Adapter-for-MQTT_1.0.0.167-x64_.tar.gz .
ENTRYPOINT ["/mqttdockerstart.sh"]

2. Copy the PI-Adapter-for-MQTT_1.0.0.167-platform_.tar.gz file to the same

directory as the Dockerfile.

3. Copy the mqttdockerstart.sh script to the same directory as the Dockerfile.

4. Run the following command line in the same directory (sudo may be necessary):

docker build -t mqttadapter .

Docker container startup

The following procedures contain instructions on how to run the adapter inside a Docker container with
different options enabled.

Run the Docker container with REST access enabled

To run the adapter inside a Docker container with access to its REST API from the local host, complete the
following steps:

1. Use the docker container image mqttadapter created previously.

2. Type the following in the command line (sudo may be necessary):

docker run -d --network host mqttadapter

Port 5590 is accessible from the host and you can make REST calls to the adapter from applications on the
local host computer. In this example, all data stored by the adapter is stored in the container itself. When
you delete the container, the stored data is also deleted.

Run the Docker container with persistent storage

To run the adapter inside a Docker container while using the host for persistent storage, complete the
following steps. This procedure also enables access to the adapter REST API from the local host.

1. Use the docker container image mqttadapter created previously.

2. Type the following in the command line (sudo may be necessary):

28 PI Adapter for MQTT Published: 19 July 2022

 docker run -d --network host -v /mqtt:/usr/share/OSIsoft/ mqttadapter

Port 5590 is accessible from the host and you can make REST calls to the adapter from applications on the
local host computer. In this example, all data that is written to the container is instead written to the host
directory and the host directory is a directory on the local machine, /mqtt. You can specify any directory.

Change port number

To use a different port other than 5590, you can specify a portnum variable on the docker run
command line. For example, to start the adapter using port 6000 instead of 5590, use the following
command:

docker run -d -e portnum=6000 --network host mqttadapter

This command accesses the REST API with port 6000 instead of port 5590. The following curl command
returns the configuration for the container.

curl http://localhost:6000/api/v1/configuration

Remove REST access

If you remove the --network host option from the docker run command, REST access is not possible
from outside the container. This may be of value where you want to host an application in the same
container as the adapter but do not want to have external REST access enabled.

Upgrade the adapter

When a new version of the adapter is released, you can upgrade to the latest version by running the new
installation package.

Windows upgrade
Complete the following steps to upgrade a PI adapter on a Windows computer:

1. Download PI-Adapter-for-MQTT_1.0.0.167-x64_.msi from the OSIsoft Customer Portal.

Note: Customer login credentials are required to access the portal.

2. Run PI-Adapter-for-MQTT_1.0.0.167-x64_.msi.

29 PI Adapter for MQTT Published: 19 July 2022

 3. Complete the setup wizard.

4. Optional: To verify the upgrade, run the following curl command with the port number that you
specified when completing the wizard:

curl -X GET "http://localhost:5590/api/v1/Diagnostics/ProductInformation"

Upon successful upgrade, the JSON response lists the updated application version:

{
"Application Version": "1.0.0.167", // upgraded version
".Net Core Version": ".NET Core 3.1.15",
"Operating System": "Microsoft Windows 10.0.19041"
}

Linux upgrade
Complete the following steps to upgrade a PI adapter on a Linux computer:

1. Download the appropriate Linux distribution file from the OSIsoft Customer Portal.

Note: Customer login credentials are required to access the portal.

2. Open a terminal session.

3. Move the Linux distribution file to the target host and run the sudo apt upgrade command.

Platform Command

Linux x64 sudo apt upgrade ./PI-Adapter-for-MQTT_1.0.0.167-x64_.deb

Linux ARM32 Debian sudo apt upgrade ./PI-Adapter-for-MQTT_1.0.0.167-arm_.deb

Linux ARM64 Debian sudo apt upgrade ./PI-Adapter-for-MQTT_1.0.0.167-

arm64_.deb

4. Optional: To verify the upgrade, run the following curl command with the port number that you
specified:

curl -X GET "http://localhost:5590/api/v1/Diagnostics/ProductInformation"

30 PI Adapter for MQTT Published: 19 July 2022

 Upon successful upgrade, the JSON response lists the updated application version:

{
"Application Version": "1.0.0.167", // upgraded version
".Net Core Version": ".NET Core 3.1.15",
"Operating System": "Microsoft Windows 10.0.19041"
}

Uninstall the adapter

Complete the procedure corresponding to your specific operating system to uninstall the adapter:

Windows
1. To delete the PI adapter program files from a Windows device, use the Windows Control Panel
uninstall application process.

Note: The configuration, data, and log files are not deleted by the uninstall process.

2. Optional: To delete data, configuration, and log files, delete the directory:

%ProgramData%\OSIsoft\Adapters\MQTT

This deletes all data processed by the adapter, in addition to the configuration and log files.

Linux
1. To delete PI Adapter software from a Linux device, open a terminal window and run the following
command:

sudo apt remove pi.adapter.MQTT

2. Optional: To delete data, configuration, and log files, run the following command:

sudo rm -r /usr/share/OSIsoft/Adapters/MQTT

This deletes all data processed by the adapter, in addition to the configuration and log files.

31 PI Adapter for MQTT Published: 19 July 2022

 Configuration
PI Adapter for MQTT provides configuration of data source, discovery, and data selection for both the
generic and the Sparkplug B component.

The examples in the configuration topics use curl, a commonly available tool on both Windows and Linux.
You can configure the adapter with any programming language or tool that supports making REST calls or
with the EdgeCmd utility. For more information, see the EdgeCmd utility documentation. To validate
successful configurations, you can perform data retrieval (GET commands) with a browser, if available, on
your device.

For more information on PI Adapter configuration tools, see Configuration tools.

Quick start
This Quick Start guides you through setup of each configuration file available for PI Adapter for MQTT. As
you complete each step, perform each required configuration to establish a data flow from a data source to
one or more endpoints. Some configurations are optional.

Important: If you want to complete the optional configurations, complete those tasks before the required
tasks.

1. Configure one or more MQTT system components.

See System components.

2. Configure an MQTT data source for each MQTT device.

See Data source (generic) and Data source (Sparkplug B).

3. Optional: Configure data discovery. See Discovery.

4. Configure an MQTT data selection for each MQTT data source.

See Data selection (generic) and Data selection (Sparkplug B).

5. Optional: Configure data filters, diagnostics and metadata, buffering, logging, and if there is a proxy
between the adapter and your egress endpoints, define it.
See the following topics:

• Data filters

• Diagnostics and metadata

• Buffering

• Logging

• Configure a network proxy

6. Configure one or more egress and health endpoints.

See Egress endpoints and Health endpoints.

32 PI Adapter for MQTT Published: 19 July 2022

 Security
When determining MQTT security practices with regards to REST APIs, you should consider the following
practice. To keep the adapter secure, only administrators should have access to machines where the adapter
is installed. REST APIs are bound to localhost, meaning that only requests coming from within the machine
will be accepted.

Configuration tools
You can configure PI adapters with the EdgeCmd utility, OSIsoft's proprietary tool for configuring adapters,
or a commonly-used REST tool.

EdgeCmd utility
The EdgeCmd utility enables adapter configuration on both Linux and Windows operating systems. For
more information on using the EdgeCmd utility, see the EdgeCmd utility documentation.

REST tools
The following tools are available to make REST calls:

curl
curl is a command line tool used to make HTTP calls and is supported on both Windows and Linux operating
systems. You can script curl with Bash or PowerShell on Linux or Windows and you can use it to perform
adapter administrative and programming tasks. curl commands are used in configuration and
management examples throughout this document. For more information, see curl (https://curl.haxx.se/).

Postman
Postman is a REST tool for systems with GUI components. PI adapters are supported on platforms without
GUIs. Postman is particularly useful for learning more about PI Adapter REST APIs. For more information,
see Postman (https://www.postman.com/).

System components
PI Adapter for MQTT uses JSON configuration files in a protected directory on Windows and Linux to store
configuration that is read on startup. While the files are accessible to view, OSIsoft recommends that you
use REST or the EdgeCmd utility for any changes you make to the files.

As part of making adapters as secure as possible, any passwords or secrets that you configure are stored in
encrypted form where cryptographic key material is stored separately in a secure location. If you edit the
files directly, the adapter may not work as expected.

33 PI Adapter for MQTT Published: 19 July 2022

 Note: You can edit any single component or facet of the system individually using REST, but you can also
configure the system as a whole with a single REST call.

Configure system components

Complete the following steps to configure system components. Use the PUT method in conjunction with
the http://localhost:5590/api/v1/configuration/system/components REST endpoint
to initialize the configuration.

1. Using a text editor, create an empty text file.

2. Copy and paste an example configuration for system components into the file.

For sample JSON, see Examples.

3. Update the example JSON parameters for your environment.

For a table of all available parameters, see System components parameters.

4. Save the file. For example, as ConfigureComponents.json.

5. Open a command line session. Change directory to the location of ConfigureComponents.json.

6. Enter the following cURL command (which uses the PUT method) to initialize the system components
configuration.

curl -d "@ConfigureComponents.json" -H "Content-Type: application/json" -X PUT "http://localh

ost:5590/api/v1/configuration/system/components"

Notes:

• If you installed the adapter to listen on a non-default port, update 5590 to the port number in
use.

• For a list of other REST operations you can perform, like updating or deleting a system
components configuration, see REST URLs.

System components schema

The full schema definition for the system components configuration is in the
System_Components_schema.json file located in one of the following folders:

Windows: %ProgramFiles%\OSIsoft\Adapters\AdapterName\Schemas

Linux: /opt/OSIsoft/Adapters/AdapterName/Schemas

34 PI Adapter for MQTT Published: 19 July 2022

 System components parameters
You can configure the following parameters for system components:

Parameters Required Type Description

ComponentId Required string The ID of the component1 . It can be any alphanumeric string. A
properly configured ComponentID follows these rules:
Cannot contain leading or trailing space
Cannot use the following characters:
> < / : ? # [ ] @ ! $ & * " ( ) \\ + , ; = `

ComponentType Required string The type of the component. There are two types of components:
OmfEgress and the adapter.1

1Note: The OmfEgress component is required to run the adapter. Both its ComponentId and
ComponentType are reserved and should not be modified.

Examples
Default system components configuration
The default System_Components.json file for the System component contains the following information.

[
{
"ComponentId": "OmfEgress",
"ComponentType": "OmfEgress"
}
]

System components configuration with two adapter instances

[
{
"componentId": "OmfEgress",
"componentType": "OmfEgress"
},
{
"componentId": "MQTT1",
"componentType": "MQTT"
},

35 PI Adapter for MQTT Published: 19 July 2022

 {
"componentId": "MQTTSparkplugB1",
"componentType": "MQTTSparkplugB"
}
]

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/system/components GET Retrieves the system components configuration

api/v1/configuration/system/components POST Adds a new component to the system configuration

api/v1/configuration/system/components PUT Updates the system components configuration

api/v1/configuration/system/components/ DELETE Deletes a specific component from the system

ComponentId components configuration

api/v1/configuration/system/components/ PUT Creates a new component with the specified

ComponentId ComponentId in the system configuration

System and adapter

You can configure the system component and adapter component together using a single file.

Change system and adapter configuration

Complete the following steps to configure system and adapter. Use the PUT method in conjunction with the
http://localhost:5590/api/v1/configuration REST endpoint to initialize the configuration.

1. Using a text editor, create an empty text file.

2. Copy and paste an example configuration for system and adapter into the file.

For sample JSON, see the corresponding adapter configuration examples topic.

3. Save the file. For example, as ConfigureSystemAndAdapter.json.

4. Open a command line session. Change directory to the location of

ConfigureSystemAndAdapter.json.

5. Enter the following cURL command (which uses the PUT method) to initialize the system and adapter
configuration.

36 PI Adapter for MQTT Published: 19 July 2022

 curl -d "@ConfigureSystemAndAdapter.json" -H "Content-Type: application/json" -X PUT "http:/
/localhost:5590/api/v1/configuration"

Notes:

• If you installed the adapter to listen on a non-default port, update 5590 to the port number in
use.

• In order for some of the adapter specific configurations to take effect, you have to restart the
adapter.

• Discoveries and HistoryRecoveries facet details are not required to be supplied as part of the
configuration and supplied values will be ignored. Their results will be restored from the
previous states.

If the operation fails due to errors in the configuration, the count of the error and suitable error messages
are returned in the result.

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/ PUT Replaces the configuration for the entire adapter

Data source (generic)

To use the adapter, you must configure the data source from which it polls data.

Configure MQTT data source

Complete the following steps to configure an MQTT data source. Use the PUT method in conjunction with
the api/v1/configuration/<ComponentId>/DataSource REST endpoint to initialize the
configuration.

1. Using a text editor, create an empty text file.

2. Copy and paste an example configuration for an MQTT data source into the file.

For sample JSON, see MQTT data source examples.

3. Update the example JSON parameters for your environment.

For a table of all available parameters, see MQTT data source parameters.

4. Save the file. For example, as ConfigureDataSource.json.

37 PI Adapter for MQTT Published: 19 July 2022

 5. Open a command line session. Change directory to the location of ConfigureDataSource.json.

6. Enter the following cURL command (which uses the PUT method) to initialize the data source
configuration.

curl -d "@ConfigureDataSource.json" -H "Content-Type: application/json" -X PUT "http://localho

st:5590/api/v1/configuration/MQTT1/DataSource"

Notes:

• If you installed the adapter to listen on a non-default port, update 5590 to the port number in
use.

• If you use a component ID other than MQTT1, update the endpoint with your chosen
component ID.

• For a list of other REST operations you can perform, like updating or deleting a data source
configuration, see REST URLs.

7. Configure data selection.

For more information, see PI Adapter for MQTT data selection configuration.

MQTT data source schema

The full schema definition for the MQTT data source configuration is in the
MQTT_DataSource_schema.json file located in one of the following folders:

• Windows: %ProgramFiles%\OSIsoft\Adapters\MQTT\Schemas

• Linux: /opt/OSIsoft/Adapters/MQTT/Schemas

MQTT data source parameters

The following parameters are available for configuring an MQTT data source:

Parameter Required Type Description

HostNameOrIpAddress Required string Host name or IP address of the MQTT server

Allowed value: Any valid WS or TCP/IP endpoint address

Default value: null

38 PI Adapter for MQTT Published: 19 July 2022

 Parameter Required Type Description

Port Optional integer Port number of the MQTT server. Required only if Protocol
is TCP.

Allowed value: Valid port range or null

Default value if Protocol is TCP: 8883
Default value if Protocol is WS: null

Protocol Optional enum The protocol used to communicate to the MQTT broker

Allowed value: WS or TCP

Default value: TCP

TLS Optional enum Determines if TLS should be used and what version

Allowed value: None, TLS, TLS11, TLS12, TLS13

Default value: TLS12

UserName Optional string User name or client Id for accessing the MQTT server

Allowed value: any string

Default value: null

Password Optional string Password or token for accessing the MQTT server

Note: OSIsoft recommends using REST to configure the

data source when the password must be specified because
the adapter will encrypt the password when using REST. If
you do not use REST, the plain text password is stored on-
disk. You cannot specify a Password without specifying a
UserName.

Allowed value: Any string

Default value: null

ClientId Optional string Unique identification of the adapter component connecting

to the MQTT broker

Note: If the ClientId is null, the adapter generates a GUID.

MQTTVersion Optional enum Version of the MQTT protocol to be used

Allowed value: 3.1.0, or 3.1.1, or 5.0.0

Default value: 3.1.1

ValidateServerCertificate Optional boolean Determines if the server certificate gets validated

Note: A warning is printed in case the server certificate

validation is disabled.
Default value: true

39 PI Adapter for MQTT Published: 19 July 2022

 Parameter Required Type Description

StreamIdPrefix Optional string Specifies what prefix is used for stream Ids. The naming
convention is {StreamIdPrefix}{StreamId}. An
empty string means no prefix is added to the stream Ids and
names. A null value defaults to ComponentId followed by
a period.

Example: Mqtt1.{Topic}.{ValueField}

Note: Every time you change the StreamIdPrefix of a

configured adapter, for example when you delete and add a
data source, you need to restart the adapter for the changes
to take place. New streams are created on adapter restart
and pre-existing streams are no longer updated.

Allowed value: Any string

Default value: null

DefaultStreamIdPattern Optional string Specifies the default stream Id pattern to use. Possible
parameters: {Topic}, {ValueField}, {DataType}.

Allowed value: Any string

Default value: {Topic}.{ValueField}

TimeZone Optional string Specifies the time zone associated with data received from
the configured MQTT broker and its topics.

Allowed value: A valid entry from the IANA time zone

database, for example America/Los_Angeles, Asia/
Hong_Kong, Europe/London, etc. For more
information, see IANA Time Zone Database
Default value: null

Note: Supply this field if you are using source timestamps

and the timestamp does not contain time zone information.

Runtime changes
When you set up a new data source configuration, the adapter automatically connects to the new data
source. When you delete a data source configuration, the adapter automatically disconnects from the data
source and stops data collection for all streams associated with that data source. Additionally, when you
update existing data source properties, the changes are reflected at runtime.

Note: Runtime changes also handle validation of configuration, which means that an invalid data source
configuration is rejected.

MQTT data source examples

The following are examples of valid MQTT data source configurations:

40 PI Adapter for MQTT Published: 19 July 2022

 Minimal data source configuration

{
"HostNameOrIpAddress" : "125.0.0.0" ,
"Port" : 8765
}

Complete data source configuration

{
"StreamIdPrefix" : null,
"DefaultStreamIdPattern" : "{Topic}.{ValueField}",
"HostNameOrIpAddress" : "125.0.0.0",
"Port" : 8765,
"Protocol" : "Tcp",
"TLS" : "Tls12",
"UserName": null,
"Password": null,
"ClientId" : "Test-Client-Id",
"MQTTVersion" : "3.1.1",
"ValidateServerCertificate" : true
"timeZone": "UTC",
"streamIdPrefix": "MyPrefix.",
"defaultStreamIdPattern": "{Topic}.{ValueField}"
}

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/ GET Retrieves the MQTT data source configuration.

<ComponentId>/
DataSource

api/v1/configuration/ POST Creates the MQTT data source configuration. The adapter starts
<ComponentId>/ collecting data after the following conditions are met:
DataSource
• The MQTT data source configuration POST request is received.
• A MQTT data selection configuration is active.

41 PI Adapter for MQTT Published: 19 July 2022

 Relative URL HTTP verb Action

api/v1/configuration/ PUT Configures or updates the MQTT data source configuration.

<ComponentId>/ Overwrites any active MQTT data source configuration. If no
DataSource configuration is active, the adapter starts collecting data after the
following conditions are met:

• The MQTT data source configuration PUT request is received.

• A MQTT data selection configuration is active.

api/v1/configuration/ DELETE Deletes the MQTT data source configuration. After the request is
<ComponentId>/ received, the adapter stops collecting data.
DataSource

Note: Replace <ComponentId> with the Id of your MQTT component. For example, Mqtt1.

Data source (Sparkplug B)

To use the adapter, you must configure the data source from which it polls data.

Configure MQTT Sparkplug B data source

Complete the following steps to configure an MQTT Sparkplug B data source. Use the PUT method in
conjunction with the api/v1/configuration/<ComponentId>/DataSource REST endpoint to
initialize the configuration.

1. Using a text editor, create an empty text file.

2. Copy and paste an example configuration for an MQTT Sparkplug B data source into the file.

For sample JSON, see MQTT Sparkplug B data source examples.

3. Update the example JSON parameters for your environment.

For a table of all available parameters, see MQTT Sparkplug B data source parameters.

4. Save the file. For example, as ConfigureDataSource.json.

5. Open a command line session. Change directory to the location of ConfigureDataSource.json.

6. Enter the following cURL command (which uses the PUT method) to initialize the data source
configuration.

curl -d "@ConfigureDataSource.json" -H "Content-Type: application/json" -X PUT "http://localho

st:5590/api/v1/configuration/MQTTSparkplugB1/DataSource"

42 PI Adapter for MQTT Published: 19 July 2022

 Notes:

• If you installed the adapter to listen on a non-default port, update 5590 to the port number in
use.

• If you use a component ID other than MQTTSparkplugB1, update the endpoint with your
chosen component ID.

• For a list of other REST operations you can perform, like updating or deleting a data source
configuration, see REST URLs.

7. Configure data selection.

For more information, see PI Adapter for MQTT Sparkplug B data selection configuration.

MQTT data source schema

The full schema definition for the MQTT data source configuration is in the
MQTT_DataSource_schema.json file located in one of the following folders:

• Windows: %ProgramFiles%\OSIsoft\Adapters\MQTT\Schemas

• Linux: /opt/OSIsoft/Adapters/MQTT/Schemas

MQTT Sparkplug B data source parameters

The following parameters are available for configuring an MQTT data source:

Parameter Required Type Description

HostNameOrIpAddress Required string Host name or IP address of the MQTT server

Allowed value: Any valid WS or TCP/IP endpoint address

Port Optional integer Port number of the MQTT server. Required only if Protocol
is TCP.

Allowed value: Valid port range or null

Default value if Protocol is TCP: 8883
Default value if Protocol is WS: null

PrimaryHostId Optional string The Id of the primary host. The adapter is considered the
primary application.

Allowed value: Any string without the following characters:

+ # /
Default value: null

43 PI Adapter for MQTT Published: 19 July 2022

 Parameter Required Type Description

Protocol Optional enum The protocol used to communicate to the MQTT broker

Allowed value: WS or TCP

Default value: TCP

TLS Optional enum Determines if TLS should be used and what version

Allowed value: None, TLS, TLS11, TLS12, TLS13

Default value: TLS12

UserName Optional string User name or client Id for accessing the MQTT server

Allowed value: Any string

Default value: null

Password Optional string Password or token for accessing the MQTT server

Note: OSIsoft recommends using REST to configure the

data source when the password must be specified because
REST will encrypt the password. If you do not use REST, the
plain text password is stored on-disk. You cannot specify a
PassWord without specifying a UserName.

Allowed value: Any string

Default value: null

ClientId Optional string Unique identification of the adapter component connecting

to the MQTT broker

Note: If ClientId is null, the adapter generates a GUID.

MQTTVersion Optional enum Version of the MQTT protocol to be used

Allowed value: 3.1.0, or 3.1.1, or 5.0.0

Default value: 3.1.1

ValidateServerCertificate Optional boolean Determines if server certificate gets validated

Note: A warning is printed in case the server certificate

validation is disabled.
Default value: true

44 PI Adapter for MQTT Published: 19 July 2022

 Parameter Required Type Description

StreamIdPrefix Optional string Specifies what prefix is used for stream Ids. The naming
convention is {StreamIdPrefix}{StreamId}. An
empty string means no prefix is added to the stream Ids and
names. A null value defaults to ComponentId followed by
a period.

Example: MqttSparkplugB1.{Topic}.
{MetricName}

Note: Every time you change the StreamIdPrefix of a

configured adapter, for example when you delete and add a
data source, you need to restart the adapter for the changes
to take place. New streams are created on adapter restart
and pre-existing streams are no longer updated.

Allowed value: any string

Default value: null

DefaultStreamIdPattern Optional string Specifies the default stream Id pattern to use. The MQTT
{BaseTopic} string has the following format:
{namespace}/{groupId}/{edgeNodeId}/
{deviceId} Possible parameters: {BaseTopic},
{Topic}, {MetricName}.

Allowed value: any string

Default value: {BaseTopic}.{MetricName}

Runtime changes
When you set up a new data source configuration, the adapter automatically connects to the new data
source. When you delete a data source configuration, the adapter automatically disconnects from the data
source and stops data collection for all streams associated with that data source. Additionally, when you
update existing data source properties, the changes are reflected at runtime.

Note: Runtime changes also handle validation of configuration, which means that an invalid data source
configuration is rejected.

MQTT Sparkplug B data source examples

The following are examples of valid MQTT Sparkplug B data source configurations:

Minimal data source configuration

{
"HostNameOrIpAddress" : "148.101.185.11",

45 PI Adapter for MQTT Published: 19 July 2022

 "Port" : 1883,
}

Complete data source configuration

{
"HostNameOrIpAddress" : "148.101.185.11",
"Port" : 1883,
"PrimaryHostId" : "Optimus",
"Protocol" : "Tcp",
"TLS" : "Tls12",
"UserName" : "SampleUser",
"PassWord" : "SamplePassword",
"ClientId" : "734029baf8f04bb2be99750381d6602a",
"MQTTVersion" : "3.1.1",
"ValidateServerCertificate" : true,
"StreamIdPrefix" : null,
"DefaultStreamIdPattern" : "{Topic}.{MetricName}"
}

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/ GET Retrieves the MQTT Sparkplug B data source configuration.

<ComponentId>/
DataSource

api/v1/configuration/ POST Creates the MQTT Sparkplug B data source configuration. The adapter
<ComponentId>/ starts collecting data after the following conditions are met:
DataSource
• The MQTT Sparkplug B data source configuration POST request is
received.
• A MQTT Sparkplug B data selection configuration is active.

api/v1/configuration/ PUT Configures or updates the MQTT Sparkplug B data source

<ComponentId>/ configuration. Overwrites any active MQTT Sparkplug B data source
DataSource configuration. If no configuration is active, the adapter starts collecting
data after the following conditions are met:

• The MQTT Sparkplug B data source configuration PUT request is

received.
• A MQTT Sparkplug B data selection configuration is active.

46 PI Adapter for MQTT Published: 19 July 2022

 Relative URL HTTP verb Action

api/v1/configuration/ DELETE Deletes the MQTT Sparkplug B data source configuration. After the
<ComponentId>/ request is received, the adapter stops collecting data.
DataSource

Note: Replace <ComponentId> with the Id of your MQTT Sparkplug B component. For example,
MqttSparkplugB1.

Client settings
The client settings configuration is automatically generated when a new data source is added. If you
experience problems with timeouts or when MQTT limits are exceeded in terms of browse or subscription
operation, you can change the client settings configuration.

Configure MQTT client settings

Complete the following steps to configure MQTT client settings. Use the PUT method in conjunction with
the api/v1/configuration/<ComponentId>/ClientSettings REST endpoint to initialize the
configuration.

1. Using a text editor, create an empty text file.

2. Copy and paste an example configuration for MQTT client settings into the file.

For sample JSON, see MQTT client settings example.

3. Update the example JSON parameters for your environment.

For a table of all available parameters, see MQTT client settings parameters.

4. Save the file. For example, as ConfigureClientSettings.json.

5. Open a command line session. Change directory to the location of

ConfigureClientSettings.json.

6. Enter the following cURL command (which uses the PUT method) to initialize the client settings
configuration.

curl -d "@ConfigureClientSettings.json" -H "Content-Type: application/json" -X PUT "http://local

host:5590/api/v1/configuration/MQTT1/ClientSettings"

Notes:

47 PI Adapter for MQTT Published: 19 July 2022

 • If you installed the adapter to listen on a non-default port, update 5590 to the port number in
use.

• If you use a component ID other than MQTT1, update the endpoint with your chosen
component ID.

• For a list of other REST operations you can perform, like updating or deleting a client settings
configuration, see REST URLs.

MQTT client settings schema

The full schema definition for the MQTT client settings configuration is in the
MQTT_ClientSettings_schema.json file located in one of the following folders:

Windows: %ProgramFiles%\OSIsoft\Adapters\MQTT\Schemas

Linux: /opt/OSIsoft/Adapters/MQTT/Schemas

MQTT client settings parameters

The following parameters are available for configuring MQTT client settings:

Parameter Required Type Description

KeepAlivePeriod Optional string The maximum time that can elapse between sending two data
(timespan) items.

Allowed value: >= 00:00:05 (5 seconds)

Default value: 00:00:30 (30 seconds)

QosLevel Optional integer Defines the guarantee of delivery for a specific item.

or Allowed value:
0 or AtMostOnce: There is no guarantee of item delivery
enum 1 or AtLeastOnce: An item is delivered at least one time
2 or ExactlyOnce: Each item is received only one time.
Default value: 2

MaxClientQueueSize Optional integer Maximum number of items that can be in the adapter internal
queue.

Allowed value: >= 250

Default value: 1000

48 PI Adapter for MQTT Published: 19 July 2022

 MQTT client settings example

{
"keepAlivePeriod": "0:00:30",
"qosLevel": 2,
"maxClientQueueSize": 1000
}

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/ComponentId/ GET Retrieves the MQTT client settings configuration

ClientSettings

api/v1/configuration/ComponentId/ PUT Configures or updates the MQTT client settings

ClientSettings configuration

api/v1/configuration/ComponentId/ DELETE Deletes the MQTT client settings configuration

ClientSettings

api/v1/configuration/ComponentId/ PATCH Allows partial updating of configured client settings

ClientSettings fields.

Note: Replace ComponentId with the Id of your MQTT component, for example MQTT1.

Discovery
You can perform a data discovery for existing data items on demand. Data discovery is initiated through
REST calls and it is tied to a specific discovery Id, which you can either specify or let the adapter generate it.

Data discovery includes different routes. For example, you can choose to do the following:

• Retrieve the discovery results

• Query the discovery status

• Cancel or delete discoveries

• Merge discovery results with the data selection configuration

• Retrieve results from a current discovery and compare it with results from a previous or discovery

• Retrieve results from a current discovery and compare it with results from a current data selection
configuration

49 PI Adapter for MQTT Published: 19 July 2022

 Configure discovery
1. Start any of the Configuration tools capable of making HTTP requests.

2. Run a POST command with the Id of the discovery and autoSelect set to either true or false
to the following endpoint: http://localhost:5590/api/v1/configuration/
<ComponentId>/Discoveries.

Notes:

• Including an Id is optional. If you do not include one, the adapter automatically generates one.

• 5590 is the default port number. If you selected a different port number, replace it with that
value.

Example using curl:

curl -d "{ \"Id\":\"TestDiscovery\", \"autoSelect\":true }" -H "Content-Type:application/json"

-X POST "http://localhost:5590/api/v1/configuration/<ComponentId>/Discoveries"

Discovery parameters
Parameter Type Description

id string The Id of the discovery

Notes:
• You cannot run multiple discoveries with the same Id.
• Including an id is optional. If you do not include one, the adapter automatically
generates one.

query string A filter that is specific to the data source. The query filter can limit the scope of the
discovery.

For more information, see the Data source configuration topic.

startTime datetime Time when the discovery started

endTime datetime Time when the discovery ended

progress double Progress of the discovery

itemsFound integer Number of data items that the discovery found on the data source

newItems integer Number of new data items that the discovery found in comparison to the previous
discovery

50 PI Adapter for MQTT Published: 19 July 2022

 Parameter Type Description

resultUri string URL at which you can access the results of the discovery

autoSelect boolean When set to true, the result of the discovery gets pushed to the data selection
configuration.

status reference Status of the discovery, for example Active or Complete

errors string Errors encountered during the discovery

Discoveries status example

The following example shows the status of all discoveries. The discovery id in this example was auto-
generated.

[
{
"id": "8ff855f1-a636-490a-bb31-207410a6e607",
"query": null,
"startTime": "2020-09-30T19:34:01.8180401+02:00",
"endTime": "2020-09-30T19:34:01.8368776+02:00",
"progress": 30,
"itemsFound": 4,
"newItems": 0,
"resultUri": "http://127.0.0.1:5590/api/v1/Configuration/<ComponentId>/Discoveries/8ff855f1-a636
-490a-bb31-207410a6e607/result",
"autoSelect": false,
"status": "Complete",
"errors": null
}
]

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/<componentId>/ GET Returns status of all discoveries

discoveries

api/v1/configuration/<componentId>/ POST Initiates a new discovery and returns its Id

discoveries

51 PI Adapter for MQTT Published: 19 July 2022

 Relative URL HTTP verb Action

api/v1/configuration/<componentId>/ DELETE Cancels and deletes all saved discoveries

discoveries

api/v1/configuration/<componentId>/ GET Gets the status of an individual discovery

discoveries/<discoveryId>
Note: If a discovery with the specified Id does not
exist, you will get an error message

api/v1/configuration/<componentId>/ DELETE Cancels and deletes discovery and result

discoveries/<discoveryId>

api/v1/configuration/<componentId>/ GET Returns the result of a discovery

discoveries/<discoveryId>/result

api/v1/configuration/<componentId>/ GET Returns the difference between the result and the
discoveries/<discoveryId>/result? previous result
diff=previousId

api/v1/configuration/<componentId>/ GET Returns the difference between the data selection

dataselection?diff=<discoveryId> configuration and the discovery results

api/v1/configuration/<componentId>/ DELETE Cancels and deletes discovery result

discoveries/<discoveryId>/result
Note: The discovery Id is still valid, but a query will
contain a status of canceled
Only the Status property will contain a canceled
status, but not the query

api/v1/configuration/<componentId>/ POST Cancels the on-demand data source discovery

discoveries/<discoveryId>/cancel

api/v1/configuration/<componentId>/ POST Adds the discovered items to data selection with

dataselection/select? selected set to true
discoveryid=<discoveryId>

api/v1/configuration/<componentId>/ POST Adds the discovered items to data selection with

dataselection/unselect? selected set to false
discoveryid=<discoveryId>

Note: Replace <componentId> with the Id of your adapter component.

Replace <discoveryId> with the Id of the discovery for which you want to perform the action.

Data source discovery (generic)

A discovery against the data source of a generic MQTT adapter allows you to specify the optional query
parameter. The query discovers the contents of the data source and narrows down the scope of the
discovery. You can add the discovered items to the data selection.

52 PI Adapter for MQTT Published: 19 July 2022

 Note: Only one discovery at a time is supported.

Generic query string

The string of the query parameter must contain string items in the following form:
Topics=<TopicName>;WaitTime=<WaitTime>

String item Required Description

Topics Optional The topics that the adapter subscribes to when the discovery posts.
Note: If you want to specify multiple topics in the query, you must separate the topic
names with a comma. If you do not specify a topic, the adapter subscribes to all topics.

WaitTime Optional The time window in which the adapter performs the discovery by listening for specified
topics. Once the wait time elapses, the discovery results are available.

Minimum value: 0.00:00:30 (30 seconds)

Maximum value: 7.00:00:00 (7 days)
Note: If you do not specify a wait time, the default value 0.00:01:00 (1 minute) is
applied.
When you specify WaitTime with a numeric value, for example WaitTime=45, the
adapter interprets the value as seconds instead of time span.

Query rules
The following rules apply when specifying the query string:

• Only one query at a time is supported. That query can contain as many topics with the same wait time
as needed. If you need different wait times for different topics, you need to create a new query once
the query from the previous discovery has completed.

• Partial queries are terminated by a multi-level wildcard (#).

• A query cannot be terminated by a trailing slash (/).

• A query cannot start with a leading slash (/) or $.

• Topics are case sensitive.

• White spaces are supported.

• Special characters are replaced by the text parser. For more information, see Text parser

Note: The data source might contain large amounts of metrics. Use the # judiciously and narrow down the
query string to something specific or break down the query into different discoveries.

53 PI Adapter for MQTT Published: 19 July 2022

 Wildcards
Wildcards are allowed in the query with the following specifications:

• A single-level wildcard replaces one topic level and is indicated by +.

• A multi-level wildcard covers many topic levels and is indicated by #.

• Wildcards can be combined.

• # must not be used more than once and can only be used at the end of the topic.

• No query, an empty string, or null as the query parameter is equivalent to #.

Discovery query example

The query parameter of the generic MQTT component must be specified in the following form:
Topics=<TopicName>;WaitTime=<WaitTime.

Generic data source discovery initiation

{
"id" : "SampleA",
"query" : "Topics=Sample1,Sample2;WaitTime=00:00:30"
}

Generic data source discovery results

[
{
"id" : "SampleA",
"query" : "Topics=Sample1,Sample2;WaitTime=00:00:00:30",
"startTime": "2020-12-14T14:19:01.4383791-08:00",
"endTime": "2020-12-14T14:19:31.8549164-08:00",
"progress": 30,
"itemsFound": 700,
"newItems": 200,
"resultUri": "http://127.0.0.1:5590/api/v1/Configuration/mqttComponentId/Discoveries/40/result",
"autoSelect": false,
"status": "Complete",
"errors": null

54 PI Adapter for MQTT Published: 19 July 2022

 }
]

MQTT discovered selection items

[
{
"Topic": "Sample1",
"ValueField": "$.Value4",
"IndexField": null,
"DataType": "Single",
"IndexFormat": "null",
"Selected": false,
"Name": null,
"StreamId": "Sample1.$.Value4",
"DataFilterId": null
},
{
"Topic": "Sample2",
"ValueField": "$.Value1",
"IndexField": null,
"DataType": "Single",
"IndexFormat": "null",
"Selected": false,
"Name": null,
"StreamId": "Sample1.$.Value1",
"DataFilterId": null
}
]

Data source discovery (Sparkplug B)

A discovery against the data source of an MQTT Sparkplug B adapter allows you to specify the optional
query parameter. The query discovers the contents of the data source and narrows down the scope of the
discovery. You can add the discovered items to the data selection.

55 PI Adapter for MQTT Published: 19 July 2022

 Sparkplug B query string
The string of the query parameter must contain string items in the following form:
Topics=Topic1,Topic2;WaitTime=<WaitTime> where the Sparkplug B topic structure is of the
form spBv1.0/<Group_Id>/<Message_Type>/<Edge_Node_Id>/[<Device_Id>].

String item Required Description

Group_Id Optional This element of the Topic namespace logically groups MQTT EoN nodes into the
MQTT server and the consuming MQTT clients.

Message_Type Optional This element of the Topic namespace indicates how to handle the MQTT payload of
the message. The message type is typically NDATA or DDATA. For more information,
see Data selection (Sparkplug B).

Edge_Node_Id Optional This element of the Sparkplug Topic namespace uniquely identifies the MQTT EoN
node within the infrastructure.

Device_Id Optional This element of the Sparkplug Topic namespace identifies a device attached to the
MQTT EoN node (physically or logically).

WaitTime Optional The time window in which the adapter will perform the discovery by listening for
specified topics. Once the wait time has elapsed, the discovery results will be
available.

Minimum value: 0.00:00:30 (30 seconds)

Maximum value: 7.00:00:00 (7 days)
Note: If you do not specify a wait time, the default value 0.00:01:00 (1 minute)
will be applied.
When you specify WaitTime with a numeric value, for example WaitTime=45, the
adapter interprets the value as seconds instead of time span.

Query rules
The following rules apply for specifying the query string:

• Multiple topics are separated by a comma (,).

• A query cannot be terminated by a trailing slash (/).

• A query cannot start with a leading slash (/) or $.

• Topics are case sensitive.

Note: The data source might contain large amounts of metrics. Use the # judiciously and narrow down the
query string to something specific or break down the query into different discoveries.

56 PI Adapter for MQTT Published: 19 July 2022

 Wildcards
Wildcards are allowed in the query with the following specifications:

• A single-level wildcard replaces one topic level and is indicated by +.

• A multi-level wildcard covers many topic levels and is indicated by #.

• Wildcards can be combined.

• # must not be used more than once and can only be used at the end of the topic.

• No query, an empty string, or null as the query parameter is equivalent to #.

Discovery query example

The query parameter of the MQTT Sparkplug B component must be specified in the following form:
spBv1.0/<Group_Id>/<Message_Type>/<Edge_Node_Id>/<[Device_Id]>.

Sparkplug B data source discovery initiation

{
"id" : "40",
"query" : "topics=group1/edgeNode1,group2/edgeNode2;waitTime=00:00:30"
}

Sparkplug B data source discovery results

[
{
"id": "40",
"query": "topics=group1/edgeNode1,group2/edgeNode2;waitTime=00:00:30",
"startTime": "2020-12-14T14:19:01.4383791-08:00",
"endTime": "2020-12-14T14:19:31.8549164-08:00",
"progress": 30,
"itemsFound": 700,
"newItems": 200,
"resultUri": "http://127.0.0.1:5590/api/v1/Configuration/mqttComponentId/Discoveries/40/result",
"autoSelect": false,
"status": "Complete",
"errors": null

57 PI Adapter for MQTT Published: 19 July 2022

 }
]

Data selection (generic)

In addition to the data source configuration, you need to provide a data selection configuration to specify
the data you want the adapter to collect from the data sources.

Configure MQTT data selection

Complete the following steps to configure an MQTT data selection. Use the PUT method in conjunction
with the api/v1/configuration/<ComponentId>/DataSelection REST endpoint to initialize
the configuration.

1. Using a text editor, create an empty text file.

2. Copy and paste an example configuration for an MQTT data selection into the file.

For sample JSON, see MQTT data selection examples.

3. Update the example JSON parameters for your environment.

For a table of all available parameters, see MQTT data selection parameters.

4. Save the file. For example, as ConfigureDataSelection.json.

5. Open a command line session. Change directory to the location of

ConfigureDataSelection.json.

6. Enter the following cURL command (which uses the PUT method) to initialize the data selection
configuration.

curl -d "@ConfigureDataSelection.json" -H "Content-Type: application/json" -X PUT "http://local

host:5590/api/v1/configuration/MQTT1/DataSelection"

Notes:

• If you installed the adapter to listen on a non-default port, update 5590 to the port number in
use.

• If you use a component ID other than MQTT1, update the endpoint with your chosen
component ID.

58 PI Adapter for MQTT Published: 19 July 2022

 • For a list of other REST operations you can perform, like updating or deleting a data selection
configuration, see REST URLs.

MQTT data selection schema

The full schema definition for the MQTT data selection configuration is in the
MQTT_DataSelection_schema.json file located in one of the following folders:

• Windows: %ProgramFiles%\OSIsoft\Adapters\MQTT\Schemas

• Linux: /opt/OSIsoft/Adapters/MQTT/Schemas

MQTT data selection parameters

Parameter Required Type Description

Selected Optional boolean Selects or clears a measurement. To select an item, set

the field to true. To remove an item, leave the field
empty or set the value to false.

Allowed value: true or false

Default value: true

Name Optional string The optional friendly name of the data item collected
from the data source.

Allowed value: Any string

Default value: null

59 PI Adapter for MQTT Published: 19 July 2022

 Parameter Required Type Description

StreamId Optional string The custom stream Id that is used to create the streams.
If you do not specify the StreamId, the adapter
generates a default stream Id based on the DataSource
parameter. For more information, see PI Adapter for
MQTT data source configuration. A properly configured
custom stream Id follows these rules:

Is not case-sensitive
Can contain spaces
Can contain front slashes (/)
Can contain a maximum of 100 characters
Cannot start with two underscores (__)
Cannot start or end with a period
Cannot contain consecutive periods
Cannot consist of only periods

The default Id automatically updates when there are

changes to the measurement and follows the format of
<Topic>.<MetricName>.

For more information on how the adapter encodes

special characters in the StreamId, see Egress
endpoints.

DataFilterId Optional string The Id of the data filter.

Allowed value: Any string

Default value: null
Note: If the specified DataFilterId does not exist,
unfiltered data is sent until that DataFilterId is created.

Topic Required string The MQTT topic string.

Allowed value: Cannot be null, empty, or whitespace.

ValueField Required string The JSONPath expression used to extract the data value
from a property within the payload supplied by the
MQTT server. A valid JSONPath expression starts with
$. 1

Allowed value: Cannot be null, empty, or whitespace.

For more information about JSONPath expression
syntax, see JSONPath syntax for value retrieval.

60 PI Adapter for MQTT Published: 19 July 2022

 Parameter Required Type Description

IndexField Optional string The JSONPath expression to take value to use as a

timestamp from a property. A valid JSONPath
expression starts with $. For more information about
JSONPath expression syntax, see JSONPath syntax for
value retrieval. 2

Note: The adapter generates a timestamp when null

is specified.

Allowed value: Any valid JSONPath expression

IndexFormat Optional string The time format of the timestamp value specified in the
IndexField property. 2

Allowed value: Any string that can be used as a

DateTime format in the .NET
DateTime.TryParseExact()method, for example
01/30/2021.
For more information, see DateTime.TryParseExact
Method

Note: If the string cannot be parsed, specify a custom

DateTime string or one of the following keywords:
Adapter, UnixTimeSeconds,
UnixTimeMilliseconds
Default value: null

DataType Required string The expected data type of the values for the specified
field.

Input MQTT data types are Int16, Int32, Int64,

UInt16, UInt32, UInt64, Float32, Float64,
Boolean, String, Date-Time.

Input MQTT complex data types are Geolocation

and Coordinates.

For more information, see also Principles of operation.

61 PI Adapter for MQTT Published: 19 July 2022

 Parameter Required Type Description

DataFields Required dictionary<string, A dictionary of values with key-value pairs. The keys are
string> specific fields for a complex type and the values are the
JSONPath expression used to extract the data value
from a property within the payload supplied by the
MQTT server. A valid JSONPath expression starts with
$. 1

Allowed keys: Latitude, Longitude, x, y, z. For

more information about JSONPath expression syntax,
see JSONPath syntax for value retrieval.
Default value: null

1 ValueField and DataFields are mutually exclusive. For example, if you specify ValueField, you cannot
specify DataFields and vice versa.

2 If you do not specify IndexField and IndexFormat, the adapter automatically sets the latter to Adapter,

which uses an adapter-supplied timestamp for the data. The timestamp is taken after the data is published
to the adapter while the adapter processes it. If you specify IndexFormat only with a value other than
Adapter, the validation fails and the adapter throws an error.

CSV export/import with complex types

EdgeCmd utility supports the export and import of data selection with complex types, such as Geolocation
and Coordinates. For example, the following command writes the data selection contents to a CSV file:

edgecmd get DataSelection -cid MQTT1 -file <fileName>.csv -csv

After the CSV file is created, you can use type <fileName>.csv to display the contents of the file. The
output will look similar to the following example in which the keywords are in the first line and the values,
including complex types, are in the second line:

topic,valueField,dataFields,indexField,dataType,indexFormat,selected,name,streamId,dataFilterId
mqtt/Boilers/Boiler1,,"{""X"":"".xValue]"",""Y"":""$.yValue"",""Z"":""$.zValue""}",$['Timestamp'],Coordi
nates,,True,,mqtt/Boilers/Boiler1.$.xValue.$.yValue.$.zValue,

Runtime changes
When you create a new data selection item with a new Topic property, the adapter automatically subscribes
the topic to the data source and starts data collection for the stream associated with the data selection item.
When you delete a data selection item, the adapter automatically stops collecting data for that item.
Additionally, when you update a data selection item, the adapter updates the stream and continues data
collection.

62 PI Adapter for MQTT Published: 19 July 2022

 Note: Runtime changes also handle validation of configuration, which means that an invalid data selection
configuration is rejected.

MQTT data selection examples

The following are examples of valid MQTT data selection configurations1:

Minimal data selection configuration

[
{
"Topic" : "RandomTopic",
"ValueField" : "$.TestNode[:1].Value",
"DataType" : "uint64"
}
]

Complete data selection configuration

[
{
"Selected" : true,
"Name" : null,
"StreamId" : "RandomStreamId",
"DataFilterId" : null,
"Topic" : "RandomTopic",
"ValueField" : null,
"IndexField" : "$.Timestamp",
"IndexFormat" : null,
"DataType" : "Geolocation",
"DataFields" : { "Latitude": "$.Float1", "Longitude": "$.Float2" }
},
{
"Selected" : true,
"Name" : null,
"StreamId" : "RandomStreamId",
"DataFilterId" : null,
"Topic" : "RandomTopic",
"ValueField" : null,
"IndexField" : "$.Timestamp",
"IndexFormat" : null,

63 PI Adapter for MQTT Published: 19 July 2022

 "DataType" : "Coordinates",
"DataFields" : { "x": "$.Float4", "y": "$.Float5", "z": "$.Float6" }
}
]

1 Note: Both ValueField and IndexField require the correct structure of the JSON payload to be specified (in
other words, what the data source returns). The previous examples use the following JSON payload
structure:

{
"TestNode": [
{
"Time": "02/17/2021 12:01:36 AM PST",
"Value": "4578"
}
]
}

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/ GET Retrieves the MQTT data selection configuration, including all data
<ComponentId>/ selection items.
DataSelection

api/v1/configuration/ PUT Configures or updates the MQTT data selection configuration. The
<ComponentId>/ adapter starts collecting data for each data selection item when the
DataSelection following conditions are met:

• The MQTT data selection configuration PUT request is received.

• A MQTT data source configuration is active.

api/v1/configuration/ DELETE Deletes the active MQTT data selection configuration. The adapter
<ComponentId>/ stops collecting data.
DataSelection

api/v1/configuration/ PATCH Allows partial updates of configured data selection items.

<ComponentId>/
DataSelection Note: The request must be an array containing one or more data
selection items. Each item in the array must include its StreamId.

api/v1/configuration/ PUT Updates or creates a new data selection item by StreamId. For new
<ComponentId>/ items, the adapter starts collecting data after the request is
DataSelection/<StreamId> received.

64 PI Adapter for MQTT Published: 19 July 2022

 Relative URL HTTP verb Action

api/v1/configuration/ DELETE Deletes a data selection item from the configuration by StreamId.
<ComponentId>/ The adapter stops collecting data for the deleted item.
DataSelection/<StreamId>

Note: Replace ComponentId with the Id of your MQTT component. For example, Mqtt1.

Data selection (Sparkplug B)

In addition to the data source configuration, you need to provide a data selection configuration to specify
the data you want the adapter to collect from the data sources.

Configure MQTT Sparkplug B data selection

Complete the following steps to configure an MQTT Sparkplug B data selection. Use the PUT method in
conjunction with the api/v1/configuration/<ComponentId>/DataSelection REST endpoint
to initialize the configuration.

1. Using a text editor, create an empty text file.

2. Copy and paste an example configuration for an MQTT Sparkplug B data selection into the file.

For sample JSON, see MQTT Sparkplug B data selection examples.

3. Update the example JSON parameters for your environment.

For a table of all available parameters, see MQTT Sparkplug B data selection parameters.

4. Save the file. For example, as ConfigureDataSelection.json.

5. Open a command line session. Change directory to the location of

ConfigureDataSelection.json.

6. Enter the following cURL command (which uses the PUT method) to initialize the data selection
configuration.

curl -d "@ConfigureDataSelection.json" -H "Content-Type: application/json" -X PUT "http://local

host:5590/api/v1/configuration/MQTTSparkplugB1/DataSelection"

Notes:

• If you installed the adapter to listen on a non-default port, update 5590 to the port number in
use.

65 PI Adapter for MQTT Published: 19 July 2022

 • If you use a component ID other than MQTTSparkplugB1, update the endpoint with your
chosen component ID.

• For a list of other REST operations you can perform, like updating or deleting a data selection
configuration, see REST URLs.

MQTT Sparkplug B data selection parameters

Parameter Required Type Description

Selected Optional boolean Selects or clears a measurement. To select an item, set to true. To
remove an item, leave the field empty or set to false.

Allowed value: true or false

Default value: true

Name Optional string The optional friendly name of the data item collected from the data
source

Allowed value: Any string

Default value: null

Topic Required string The MQTT topic string in the following format: {namespace}/
{groupId}/{messageType}/{edgeNodeId}/{deviceId}

The following rules apply to the MQTT topic string:

1. Both the topic string as a whole and the individual components are
case-sensitive
2. {namespace} must be spBv1.0 (case-sensitive)
3. {groupId} must be non-blank and can contain any character except
for + and #
4. {messageType} must be either DDATA or NDATA (uppercase)
Note: When NDATA is specified, {deviceId} must not be specified
5. edgeNodeId must be non-blank and can contain any character
except for + and #
6. {deviceId} must be non-blank and can contain any character
except for + and #

Examples:
spBv1.0/DemoCenters/DDATA/EPIC-DC004/DC004
spBv1.0/DemoCenters/NDATA/EPIC-DC004

MetricName Required string The name of the property in the metric

Allowed value: Cannot be null, empty, or whitespace.

66 PI Adapter for MQTT Published: 19 July 2022

 Parameter Required Type Description

StreamId Optional string The custom stream Id that is used to create the streams. If you do not
specify the StreamId, the adapter generates a default stream Id based on
the measurement configuration. A properly configured custom stream Id
follows these rules:

Is not case-sensitive
Can contain spaces
Can contain front slashes (/)
Can contain a maximum of 100 characters
Cannot start with two underscores (__)
Cannot start or end with a period
Cannot contain consecutive periods
Cannot consist of only periods

The default Id automatically updates when there are changes to the

measurement.

For more information on how the adapter encodes special characters in

the StreamId, see Egress endpoints.

DataFilterId Optional string The Id of the data filter

Allowed value: Any string

Default value: null
Note: If the specified DataFilterId does not exist, unfiltered data is sent
until that DataFilterId is created.

Runtime changes
When you create a new data selection item with a new Topic property, the adapter automatically subscribes
the topic to the data source and starts data collection for the stream associated with the data selection item.
When you delete a data selection item, the adapter automatically stops collecting data for that item.
Additionally, when you update a data selection item, the adapter updates the stream and continues data
collection.

Note: Runtime changes also handle validation of configuration, which means that an invalid data selection
configuration is rejected.

MQTT Sparkplug B data selection examples

The following are examples of valid MQTT Sparkplug B data selection configurations:

Minimal data selection configuration

[
{
"Topic" : "spBv1.0/group1/DDATA/EdgeNode1/Device1",

67 PI Adapter for MQTT Published: 19 July 2022

 "MetricName" : "Temperature"
}
]

Complete data selection configuration

[
{
"Selected" : true,
"Name" : "Temperature",
"Topic" : "spBv1.0/group1/DDATA/edgeNode1/device1",
"MetricName" : "Device1 Temperature",
"StreamId" : "Device1.Temperature.Stream",
"DataFilterId" : null
}
]

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/ GET Retrieves the MQTT Sparkplug B data selection configuration,

<ComponentId>/ including all data selection items.
DataSelection

api/v1/configuration/ PUT Configures or updates the MQTT Sparkplug B data selection

<ComponentId>/ configuration. The adapter starts collecting data for each data
DataSelection selection item when the following conditions are met:

• The MQTT Sparkplug B data selection configuration PUT request is

received.
• A MQTT Sparkplug B data source configuration is active.

api/v1/configuration/ DELETE Deletes the active MQTT Sparkplug B data selection configuration.
<ComponentId>/ The adapter stops collecting data.
DataSelection

api/v1/configuration/ PATCH Allows partial updates of configured data selection items.

<ComponentId>/
DataSelection Note: The request must be an array containing one or more data
selection items. Each item in the array must include its StreamId.

api/v1/configuration/ PUT Updates or creates a new data selection item by StreamId. For new
<ComponentId>/ items, the adapter starts collecting data after the request is received.
DataSelection/<StreamId>

68 PI Adapter for MQTT Published: 19 July 2022

 Relative URL HTTP verb Action

api/v1/configuration/ DELETE Deletes a data selection item from the configuration by StreamId.
<ComponentId>/ The adapter stops collecting data for the deleted item.
DataSelection/<StreamId>

Note: Replace ComponentId with the Id of your MQTT Sparkplug B component. For example,
MqttSparkplugB1.

Data filters
PI adapters can be configured to perform data filtering to save network bandwidth. Every data item in the
data selection configuration can be assigned the Id of a data filter. The adapter will then filter data for those
data items based on the data filter configuration.

Note: If data filters are enabled and data quality changes, both the old and current data quality values are
passed on.

Configure data filters

Complete the following steps to configure data filters. Use the PUT method in conjunction with the
http://localhost:5590/api/v1/configuration/<ComponentId>/DataFilters REST
endpoint to initialize the configuration.

1. Using a text editor, create an empty text file.

2. Copy and paste an example configuration for data filters into the file.

For sample JSON, see Data filters example.

3. Update the example JSON parameters for your environment.

For a table of all available parameters, see Data filters parameters.

4. Save the file. For example, as ConfigureDataFilters.json.

5. Open a command line session. Change directory to the location of

ConfigureDataFilters.json.

6. Enter the following cURL command (which uses the PUT method) to initialize the data filters
configuration.

curl -d "@ConfigureDataFilters.json" -H "Content-Type: application/json" -X PUT "http://localhos

t:5590/api/v1/configuration/<ComponentId>/DataFilters"

69 PI Adapter for MQTT Published: 19 July 2022

 Notes:

• If you installed the adapter to listen on a non-default port, update 5590 to the port number in
use.

• For a list of other REST operations you can perform, like updating or deleting a data filters
configuration, see REST URLs.

On successful execution, the change that you have made to data filters takes effect immediately during
runtime.

Data filters schema

The full schema definition for the data filters configuration is in the
AdapterName_DataFilters_schema.json file located in one of the following folders:

Windows: %ProgramFiles%\OSIsoft\Adapters\<AdapterName>\Schemas

Linux: /opt/OSIsoft/Adapters/<AdapterName>/Schemas

Data filters parameters

The following parameters are available for configuring data filters:

Parameter Required Type Description

Id Required string Unique identifier for the data filter.

Allowed value: any string identifier

AbsoluteDeadband Optional double Specifies the absolute change in data value that should cause
the current value to pass the filter test.
Note: You must specify AbsoluteDeadband or
PercentChange.

Allowed value: double value representing absolute deadband

number
Default value: null

PercentChange Optional double Specifies the percent change from previous value that should
cause the current value to pass the filter test.
Note: You must specify AbsoluteDeadband or
PercentChange.

Allowed value: double value representing percent change

Default value: null

70 PI Adapter for MQTT Published: 19 July 2022

 Parameter Required Type Description

ExpirationPeriod Optional timespan The length in time that can elapse after an event before
automatically sending the next event, regardless of whether the
next event passes the filter or not. The expected format is
HH:MM:SS.### or SSS.*

Allowed value: any timespan

Default value: null

* Note: For example, "ExpirationPeriod": 5:00 and "ExpirationPeriod": 300 both specify
an expiration period of 5 minutes and 0 seconds.

Data filters example

[
{
"Id": "DuplicateData",
"AbsoluteDeadband": 0,
"PercentChange": null,
"ExpirationPeriod": "01:00:00"
}
]

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/ComponentId/ GET Gets all configured data filters.

DataFilters

api/v1/configuration/ComponentId/ DELETE Deletes all configured data filters.

DataFilters

api/v1/configuration/ComponentId/ POST Adds an array of data filters or a single data filter.

DataFilters Fails if any data filter already exists.

api/v1/configuration/ComponentId/ PUT Replaces all data.

DataFilters

api/v1/configuration/ComponentId/ PATCH Allows partial updating of configured data filter.

DataFilters

api/v1/configuration/ComponentId/ GET Gets configured data filter by id.

DataFilters/id

71 PI Adapter for MQTT Published: 19 July 2022

 Relative URL HTTP verb Action

api/v1/configuration/ComponentId/ DELETE Deletes configured data filter by id.

DataFilters/id

api/v1/configuration/ComponentId/ PUT Replaces data filter by id. Fails if data filter does not
DataFilters/id exist.

Note: Replace ComponentId with the Id of your adapter component.

Diagnostics and metadata

You can configure PI adapters to produce and store diagnostics data at a designated health endpoint, and to
send metadata for created streams. For more information about available diagnostics data, see Adapter
diagnostics and Egress diagnostics. For more information about available metadata and what metadata are
sent per metadata level, see Adapter Metadata.

Configure general
1. Start any of the Configuration tools capable of making HTTP requests.

2. Run a PUT command to the following endpoint, setting EnableDiagnostics to either true or
false, MetadataLevel to None, Low, Medium, or High and HealthPrefix to a string or
null: http://localhost:5590/api/v1/configuration/system/general

Note: 5590 is the default port number. If you selected a different port number, replace it with that
value.

Example using curl:

curl -d "{ \"EnableDiagnostics\":true, \"MetadataLevel\":Medium, \"HealthPrefix\":\"Machine1\" }

" -X PUT "http://localhost:5590/api/v1/configuration/system/general"

General schema
The full schema definition for the general configuration is in the System_General_schema.json file
located in one of the following folders:

Windows: %ProgramFiles%\OSIsoft\Adapters\<AdapterName>\Schemas

Linux: /opt/OSIsoft/Adapters/<AdapterName>/Schemas

72 PI Adapter for MQTT Published: 19 July 2022

 General parameters
The following parameters are available for configuring general:

Parameter Required Type Description

EnableDiagnostics Optional boolean Determines if diagnostics are enabled

Allowed value: true or false

Default value: true

MetadataLevel Optional reference Defines amount of metadata sent to OMF endpoints.

Allowed value: None, Low, Medium, and High

Default value: Medium

HealthPrefix Optional reference Prefix to use for health and diagnostics stream and asset IDs.
Default value: null

Example
Retrieve the general configuration
Example using curl:

curl -X GET "http://localhost:{port}/api/v1/configuration/system/general"

Sample output:

{
"EnableDiagnostics": true,
"MetadataLevel": "Medium",
"HealthPrefix": "Machine1"
}

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/system/General GET Gets the general configuration

api/v1/configuration/system/General PUT Replaces the existing general configuration

73 PI Adapter for MQTT Published: 19 July 2022

 Relative URL HTTP verb Action

api/v1/configuration/system/General PATCH Allows partial updating of general configuration

Metadata
If the metadataLevel is set to Low, Medium, or High in the General configuration, adapter streams created
by the ingress components include the following metadata:

Datasource: {ComponentId}
AdapterType: {ComponentType}

ComponentId corresponds to the adapter components' data source configured in the Components
configuration. ComponentType corresponds to the adapter type.

Metadata for health and diagnostics streams

If you configure a health endpoint and enable metadata, they are included in the health streams (Device
status and Next health message expected) together with ComponentId and ComponentType.

If you enable diagnostics in General configuration, metadata are included in the diagnostics streams
(Stream count, IO rate, Error rate) together with ComponentId and ComponentType.

The adapter may also send its own stream metadata not including health and diagnostics streams. For more
information about what custom metadata is included in each stream, see the user guide for your adapter.

Note:

• Metadata is only sent for streams created by the ingress components.

• Currently, the only endpoint that persists sent metadata is OCS (OSIsoft Cloud Services).

Buffering
You can configure PI adapters to buffer data egressed from the adapter to endpoints. Buffering is configured
through the buffering configuration parameters in the system configuration.

Note: OSIsoft recommends that you do not modify the default buffering location unless it is necessary.
Changes to the buffering configuration parameters only take effect during adapter service startup.

74 PI Adapter for MQTT Published: 19 July 2022

 Configure buffering
Complete the following steps to configure buffering. Use the PUT method in conjunction with the http://
localhost:5590/api/v1/configuration/system/buffering REST endpoint to initialize the
configuration.

1. Using a text editor, create an empty text file.

2. Copy and paste an example configuration for buffering into the file.

For sample JSON, see Examples - Retrieve the buffering configuration.

3. Update the example JSON parameters for your environment.

For a table of all available parameters, see Buffering parameters.

4. Save the file. For example, as ConfigureBuffering.json.

5. Open a command line session. Change directory to the location of ConfigureBuffering.json.

6. Enter the following cURL command (which uses the PUT method) to initialize the buffering
configuration.

curl -d "@ConfigureBuffering.json" -H "Content-Type: application/json" -X PUT "http://localhost:

5590/api/v1/configuration/system/buffering"

Notes:

• If you installed the adapter to listen on a non-default port, update 5590 to the port number in
use.

• For a list of other REST operations you can perform, like updating or replacing a buffering
configuration, see REST URLs.

Buffering schema
The full schema definition for the system buffering is in the System_Buffering_schema.json file
located in one of the following folders:

Windows: %ProgramFiles%\OSIsoft\Adapters\<AdapterName>\Schemas

Linux: /opt/OSIsoft/Adapters/<AdapterName>/Schemas

75 PI Adapter for MQTT Published: 19 July 2022

 Buffering parameters
The following parameters are available for configuring buffering:

Parameter Required Type Description

EnablePersistentBuffering Optional boolean Enables or disables on-disk buffering

Allowed value: true or false

Default value: true

Note: If you disable persistent buffering, in-memory

buffering is used. On-disk and in-memory buffering are
limited by value in the MaxBufferSizeMB property.

MaxBufferSizeMB Optional integer Defines the maximum size of the buffer that is persisted on
disk 1 or used in memory 2. The unit is specified in MB (1
Megabyte = 1048576 bytes). Consider the capacity and the
type of storage medium to determine a suitable value for
this parameter.

Minimum value: 1
Maximum value: 2147483647
Default value: 1024

Note: The MaxBufferSizeMB property is applied to each

configured endpoint. For example, if you set the
MaxBufferSizeMB to 1024 and you configured the
adapter to send data to two endpoints (for example, PI
Server and OCS), the total maximum resources used for
buffering will be 2048. The health endpoint is an
exception fixed at 20 MB.

BufferLocation Required string Defines the location of the buffer files. Absolute paths are
required. Consider the access-control list (ACL) when you
set this parameter. BufferLocation is used to buffer files
when EnablePersistentBuffering is true.

Allowed value: Valid path to a folder location in the file

system
Default value:
Windows: %ProgramData%\OSIsoft\Adapters\
{AdapterInstance}\Buffers
Linux: /usr/share/OSIsoft/Adapters/{AdapterInstance}/
Buffers

1 Buffering to disk - disk is only used if required;

• Data is only written to the disk buffer if queued in the memory buffer for more than 5 seconds.

• The MaxBufferSizeMB is applied per configured endpoint except the health endpoint.

76 PI Adapter for MQTT Published: 19 July 2022

 • An adapter creates 20 MB buffer files that are stored in BufferLocation.

• When MaxBufferSizeMB is reached, the oldest buffer file is deleted and a new buffer file is created.

• The health endpoint is fixed at 20 MB. When the health endpoint buffer file becomes full, a new buffer
file is created and the previous buffer file is deleted.

Note: The following rules apply in case of an error when creating a new buffer file:

• Attempt to delete oldest buffer file and retry.

• If unable to buffer, errors are logged to indicate data loss.

• If a buffer file is corrupted, an attempt is made to recover individual records and any failure to recover
records is logged.

2 Buffering only to memory:

• The MaxBufferSizeMB is applied per configured endpoint except the health endpoint.

• When MaxBufferSizeMB is reached, the oldest messages in the memory buffer are removed.
Depending on the size of a new message, several old messages may be removed.

• The health endpoint is fixed at 20 MB. When the health endpoint buffer file becomes full, the oldest
messages in the memory buffer are removed and new messages are added.

Examples
The following examples are buffering configurations made through thecurl REST client.

Retrieve the buffering configuration

curl -X GET "http://localhost:5590/api/v1/configuration/system/buffering"

Sample output:

{
"bufferLocation": "C:/ProgramData/OSIsoft/Adapters/<AdapterName>/Buffers",
"maxBufferSizeMB": 1024,
"enablePersistentBuffering": true
}

200 OK response indicates success.

77 PI Adapter for MQTT Published: 19 July 2022

 Update MaxBufferSizeMb parameter

curl -d "{ \"MaxBufferSizeMB\": 100 }" -H "Content-Type: application/json" -X PATCH "http://localhost:5

590/api/v1/configuration/system/buffering"

204 No Content response indicates success.

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/system/buffering GET Gets the buffering configuration

api/v1/configuration/system/buffering PUT Replaces the existing buffering configuration

api/v1/configuration/system/buffering PATCH Update parameter, partial configuration

Logging
PI adapters write daily log messages for the adapter, the system, and OMF egress to flat text files in the
following locations:

• Windows: %ProgramData%\OSIsoft\Adapters{AdapterInstance}\Logs

• Linux: /usr/share/OSIsoft/Adapters/{AdapterInstance}/Logs

Each message in the log displays the message severity level, timestamp, and the message itself.

Configure logging
Complete the following steps to configure logging. Use the PUT method in conjunction with the http://
localhost:5590/api/v1/configuration/<ComponentId>/Logging REST endpoint to
initialize the configuration.

1. Using a text editor, create an empty text file.

2. Copy and paste an example configuration for logging into the file.

For sample JSON, see Example.

3. Update the example JSON parameters for your environment.

For a table of all available parameters, see Logging parameters.

4. Save the file. For example, as ConfigureLogging.json.

78 PI Adapter for MQTT Published: 19 July 2022

 5. Open a command line session. Change directory to the location of ConfigureLogging.json.

6. Enter the following cURL command (which uses the PUT method) to initialize the logging
configuration.

curl -d "@ConfigureLogging.json" -H "Content-Type: application/json" -X PUT "http://localhost:5

590/api/v1/configuration/<ComponentId>/Logging"

Notes:

• If you installed the adapter to listen on a non-default port, update 5590 to the port number in
use.

• For a list of other REST operations you can perform, like updating or retrieving a logging
configuration, see REST URLs.

• Any parameter not specified in the updated configuration file reverts to the default schema
value

On successful execution, the log-level change takes effect immediately during runtime. The other
configurations (log file size and file count) are updated after the adapter is restarted.

Logging schema
The full schema definition for the logging configuration is in the component specific logging file:
AdapterName_Logging_schema.json, OmfEgress_Logging_schema.json, or
System_Logging_schema.json file located in one of the following folders:

Windows: %ProgramFiles%\OSIsoft\Adapters\<AdapterName>\Schemas

Linux: /opt/OSIsoft/Adapters/<AdapterName>/Schemas

Logging parameters
The following parameters are available for configuring logging:

79 PI Adapter for MQTT Published: 19 July 2022

 Parameter Required Type Description

LogLevel Optional reference The logLevel sets the minimum severity for messages to be
included in the logs.
Messages with a severity below the level set are not included.

The log levels in their increasing order of severity are as

follows: Trace, Debug, Information, Warning, Error,
Critical, and None.
Default log level: Information

For detailed information about the log levels, see LogLevel.

LogFileSizeLimitBytes Optional integer The maximum size (in bytes) of log files that the service will
create for the component. The value must be a positive
integer.

Minimum value: 1000

Maximum value: 9223372036854775807
Default value: 34636833

LogFileCountLimit Optional integer The maximum number of log files that the service will create
for the component. The value must be a positive integer.

Minimum value: 1
Maximum value: 2147483647
Default value: 31

LogLevel
Level Description

Trace Logs that contain the most detailed messages. These messages may contain sensitive application
data like actual received values, which is why these messages should not be enabled in production
environment.

Note: Trace is translated to Verbose in the log file.

Debug Logs that can be used to troubleshoot data flow issues by recording metrics and detailed flow related
information.

Information Logs that track the general flow of the application. Any non-repetitive general information like the
following can be useful for diagnosing potential application errors:
- Version information related to the software at startup
- External services used
- Data source connection string
- Number of measurements
- Egress URL
- Change of state “Starting” or “Stopping”
- Configuration

80 PI Adapter for MQTT Published: 19 July 2022

 Level Description

Warning Logs that highlight an abnormal or unexpected event in the application flow that does not otherwise
cause the application execution to stop. Warning messages can indicate an unconfigured data source
state, an insecure communication channel in use, or any other event that could require attention but
that does not impact data flow.

Error Logs that highlight when the current flow of execution is stopped due to a failure. These should
indicate a failure in the current activity and not an application-wide failure. It can indicate an invalid
configuration, unavailable external endpoint, internal flow error, and so on.

Critical Logs that describe an unrecoverable application or system crash or a catastrophic failure that
requires immediate attention. This can indicate application wide failures like beta timeout expired,
unable to start self-hosted endpoint, unable to access vital resource (for example, Data Protection
key file), and so on.

Note: Critical is translated to Fatal in the log file.

None Logging is disabled for the given component.

Example
Default logging configuration
By default, logging captures Information, Warning, Error, and Critical messages in the message logs. The
following logging configuration is the installation default for a component:

{
"logLevel": "Information",
"logFileSizeLimitBytes": 34636833,
"logFileCountLimit": 31
}

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/System/Logging GET Retrieves the system logging configuration

api/v1/configuration/System/Logging PUT Updates the system logging configuration

api/v1/configuration/ComponentId/Logging GET Retrieves the logging configuration of the specified

adapter component

api/v1/configuration/ComponentId/Logging PUT Updates the logging configuration of the specified

adapter component

81 PI Adapter for MQTT Published: 19 July 2022

 Note: Replace ComponentId with the Id of your adapter component.

Egress endpoints
PI adapters collect time series data, which they can send to a permanent data store (endpoint). This
operation is called data egress. The following endpoints are available for data egress:

• OSIsoft Cloud Services (OCS)

• PI servers through PI Web API

For long term storage and analysis, you can configure any adapter to send time series data to one or several
of these endpoints in any combination. An egress endpoint is comprised of the properties specified under
Egress endpoint parameters.

Data egress to a PI server creates a PI point in the PI adapter configuration. Data egress to OCS creates a
stream in the PI adapter configuration.

The name of the PI point or OCS stream is a combination of the StreamIdPrefix specified in the adapter data
source configuration and the StreamId specified in the adapter data selection configuration.

Configure egress endpoints

Complete the following steps to configure egress endpoints. Use the PUT method in conjunction with the
http://localhost:5590/api/v1/configuration/OmfEgress/dataendpoints REST
endpoint to initialize the configuration.

1. Using a text editor, create an empty text file.

2. Copy and paste an example configuration for egress endpoints into the file.

For sample JSON, see Examples.

3. Update the example JSON parameters for your environment.

For a table of all available parameters, see Egress endpoint parameters.

4. Save the file. For example, as ConfigureEgressEndpoints.json.

5. Open a command line session. Change directory to the location of

ConfigureEgressEndpoints.json.

6. Enter the following cURL command (which uses the PUT method) to initialize the egress endpoints
configuration.

82 PI Adapter for MQTT Published: 19 July 2022

 curl -d "@ConfigureEgressEndpoints.json" -H "Content-Type: application/json" -X PUT "http://lo
calhost:5590/api/v1/configuration/OmfEgress/dataendpoints"

Notes:

• If you installed the adapter to listen on a non-default port, update 5590 to the port number in
use.

• For a list of other REST operations you can perform, like updating or replacing an egress
endpoints configuration, see REST URLs.

Egress endpoint configuration schema

The full schema definition for the egress endpoint configuration is in the
OmfEgress_DataEndpoints_schema.json file located in one of the following folders:

Windows: %ProgramFiles%\OSIsoft\Adapters\<AdapterName>\Schemas

Linux: /opt/OSIsoft/Adapters/<AdapterName>/Schemas

Egress endpoint parameters

The following parameters are available for configuring egress endpoints:

Parameter Required Type Description

Id Optional string Unique identifier

Allowed value: any string identifier

Default value: new GUID

Endpoint Required string Destination that accepts OMF v1.2 messages.

Supported destinations include OCS and PI Server.

Allowed value: well-formed http or https endpoint

string
Default: null

83 PI Adapter for MQTT Published: 19 July 2022

 Parameter Required Type Description

Username Required for string Basic authentication to the PI Web API OMF endpoint
PI server
endpoint PI server:
Allowed value: any string
Default: null
Note: If your username contains a backslash, you
must add an escape character, for example, type
OilCompany\TestUser as OilCompany\
\TestUser.

Password Required for string Basic authentication to the PI Web API OMF endpoint
PI server
endpoint PI server:
Allowed value: any string
Default: null

ClientId Required for string Authentication with the OCS OMF endpoint
OCS
endpoint Allowed value: any string, can be null if the endpoint
URL schema is HTTP
Default: null

ClientSecret Required for string Authentication with the OCS OMF endpoint
OCS
endpoint Allowed value: any string, can be null if the endpoint
URL schema is HTTP
Default: null

TokenEndpoint Optional for string Retrieves an OCS token from an alternative endpoint
OCS
endpoint Allowed value: well-formed http or https endpoint
string
Default value: null

ValidateEndpointCertificate Optional boolean Disables verification of destination certificate. Note:

Only use for testing with self-signed certificates.

Allowed value: true or false

Default value: true

Special characters encoding

The adapter encodes special characters used in the data selection StreamId parameter string before
sending it to configured endpoints. The encoded characters look as follows:

Special character Encoded character

* %2a

84 PI Adapter for MQTT Published: 19 July 2022

 Special character Encoded character

' %27

` %60

" %22

? %3f

; %3b

| %7c

\ %5c

{ %7b

} %7d

[ %5b

] %5d

Examples
The following examples are valid egress configurations:

Egress data to OCS

[{
"Id": "OCS",
"Endpoint": "https://<OCS OMF endpoint>",
"ClientId": "<clientid>",
"ClientSecret": "<clientsecret>"
}]

Egress data to PI Web API

[{
"Id": "PI Web API",
"Endpoint": "https://<pi web api server>:<port>/piwebapi/omf/",
"UserName": "<username>",

85 PI Adapter for MQTT Published: 19 July 2022

 "Password": "<password>"
}]

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/omfegress/ GET Gets all configured egress endpoints

DataEndpoints

api/v1/configuration/omfegress/ DELETE Deletes all configured egress endpoints

DataEndpoints

api/v1/configuration/omfegress/ POST Adds an array of egress endpoints or a single endpoint.

DataEndpoints Fails if any endpoint already exists

api/v1/configuration/omfegress/ PUT Replaces all egress endpoints

DataEndpoints

api/v1/configuration/omfegress/ PATCH Allows partial updating of configured endpoints.

DataEndpoints Note: The request must be an array containing one or
more endpoints. Each endpoint in the array must
include its Id.

api/v1/configuration/omfegress/ GET Gets configured endpoint by Id

DataEndpoints/{Id}

api/v1/configuration/omfegress/ DELETE Deletes configured endpoint by Id

DataEndpoints/{Id}

api/v1/configuration/omfegress/ PUT Updates or creates a new endpoint with the specified Id

DataEndpoints/{Id}

api/v1/configuration/omfegress/ PATCH Allows partial updating of configured endpoint by Id

DataEndpoints/{Id}

Egress execution details

• After configuring an egress endpoint, egress is immediately run for that endpoint. Egress is handled
individually per configured endpoint. When data is egressed for the first time, types and containers
are egressed to the configured endpoint. After that only new or changed types or containers are
egressed. Type creation must be successful in order to create containers. Container creation must be
successful in order to egress data.

• If you delete an egress endpoint, data flow immediately stops for that endpoint. Buffered data in a
deleted endpoint is permanently lost.

• Type, container, and data items are batched into one or more OMF messages when egressing. As per
the requirements defined in OMF, a single message payload will not exceed 192KB in size.
Compression is automatically applied to outbound egress messages. On the egress destination, failure

86 PI Adapter for MQTT Published: 19 July 2022

 to add a single item results in the message failing. Types, containers, and data are egressed as long as
the destination continues to respond to HTTP requests.

Prepare egress destinations

OCS and PI Server destinations may require additional configuration to receive OMF messages.

OCS
To prepare OCS to receive OMF messages from the adapter, create an OMF connection in OCS. Creating an
OMF connection results in an available OMF endpoint that can be used by the adapter egress mechanism.
Complete the following steps to create an OMF connection:

1. Create a Client.

The Client Id and Client Secret will be used for the corresponding properties in the egress
configuration.

2. Create an OMF type Connection.

The connection should link the created client to an existing namespace where the data will be stored.

The OMF Endpoint URL for the connection will be used as the egress configuration Endpoint
property.

PI Server
To prepare a PI Server to receive OMF messages from the adapter, a PI Web API OMF endpoint must be
available. Complete the following steps:

1. Install PI Web API and enable the OSIsoft Message Format (OMF) Services feature.

• During configuration, choose an AF database and PI Data Archive where metadata and data will
be stored.

• The account used in an egress configuration needs permissions to create AF elements, element
templates, and PI points.

2. Configure PI Web API to use Basic authentication.

For complete steps, as well as best practices and recommendations, see the following topic in the PI
Web API User Guide: Authentication methods.

Notes:

• The certificate used by PI Web API must be trusted by the device running the adapter, otherwise the
egress configuration ValidateEndpointCertificate property needs to be set to false (this can be the
case with a self-signed certificate but should only be used for testing purposes).

87 PI Adapter for MQTT Published: 19 July 2022

 • To continue to send OMF egress messages to the PI Web API endpoint after upgrading PI Web API,
restart the adapter service.

Configure a network proxy

Some network architectures may need a network proxy between the PI adapter and the egress endpoint.
The process for configuring the adapter to egress data through a network proxy varies depending on the
proxy type.

HTTPS forward proxy

For the adapter to use an HTTPS forward proxy while egressing, configure the https_proxy environment
variable. For information on how to configure system environment variables, refer to your platform specific
documentation:

• Windows: setx

• Ubuntu: EnvironmentVariables

• Debian: EnvironmentVariables

• Docker: Environment variables in Compose

The value of this environment variable must contain the URL of the proxy server, beginning with http. The
format of the string is [user[:password]@]http://hostname[:port].

HTTPS proxy environment variable

Parameter Required Description

user Optional The user name for the HTTPS forward proxy.

password Optional The password for the HTTPS forward proxy specified user name. If you specify user,
password remains optional.

port Optional If you do not specify port, the default 80 is used.

Note: Usage of the https_proxy environment variable may affect other .NET or .NET Core applications.
If you set this environment variable, it will affect the adapter egress endpoints and the adapter health
endpoints.

Examples:

myUser@http://192.168.2.2

88 PI Adapter for MQTT Published: 19 July 2022

 myUser:myPassword@http://proxymachine.domain:3128

http://proxymachine.domain

In Windows, this may look something like:

Example of an architecture with an https forward proxy:

89 PI Adapter for MQTT Published: 19 July 2022

 Reverse proxy
For the adapter to use a reverse proxy while egressing, you must configure the reverse proxy as an egress
endpoint. For information on how to configure an egress endpoint, see Egress endpoints configuration.

Example:

[{
"Id": "PI Web API Through Proxy",
"Endpoint": "https://<reverseProxy>:<port>/piwebapi/omf/",
"UserName": "<piWebApiUser>",
"Password": "<piWebApiPassword>"
}]

Example of an architecture with a reverse proxy:

90 PI Adapter for MQTT Published: 19 July 2022

 Health endpoints
You can configure PI adapters to produce and store health data at a designated health endpoint. You can use
health data to ensure that your adapters are running properly and that data flows to the configured OMF
endpoints.

For more information about adapter health, see Adapter health.

Configure health endpoint

A health endpoint designates an OMF endpoint where adapter health information is sent. You can configure
multiple health endpoints.

Complete the following steps to configure health endpoints. Use the PUT method in conjunction with the
http://localhost:5590/api/v1/configuration/system/healthendpoints REST
endpoint to initialize the configuration.

1. Using a text editor, create an empty text file.

2. Copy and paste an example configuration for health endpoints into the file.

For sample JSON, see Examples.

3. Update the example JSON parameters for your environment.

91 PI Adapter for MQTT Published: 19 July 2022

 For a table of all available parameters, see Health endpoint parameters.

4. Save the file. For example, as ConfigureHealthEndpoints.json.

5. Open a command line session. Change directory to the location of

ConfigureHealthEndpoints.json.

6. Enter the following cURL command (which uses the PUT method) to initialize the health endpoint
configuration.

curl -d "@ConfigureHealthEndpoints.json" -H "Content-Type: application/json" -X PUT "http://lo

calhost:5590/api/v1/configuration/system/healthendpoints"

Notes:

• If you installed the adapter to listen on a non-default port, update 5590 to the port number in
use.

• For a list of other REST operations you can perform, like updating or replacing a health
endpoints configuration, see REST URLs.

Health endpoints schema

The full schema definition for the health endpoint configuration is in the
System_HealthEndpoints_schema.json file located in one of the following folders:

Windows: %ProgramFiles%\OSIsoft\Adapters\<AdapterName>\Schemas

Linux: /opt/OSIsoft/Adapters/<AdapterName>/Schemas

Health endpoint parameters

The following parameters are available for configuring health endpoints:

Parameter Required Type Description

Id Optional string Uniquely identifies the endpoint. This can be any

alphanumeric string. If left blank, a unique value is
generated automatically.

Allowed value: any string identifier

Default value: new GUID

92 PI Adapter for MQTT Published: 19 July 2022

 Parameter Required Type Description

Endpoint Required string The URL of the OMF endpoint to receive this
health data

Allowed value: well-formed http or https endpoint

string
Default: null

Username Required for PI string The username used to authenticate with a PI Web
Web API API OMF endpoint
endpoints
PI server:
Allowed value: any string
Default: null

Password Required for PI string The password used to authenticate with a PI Web
Web API API OMF endpoint
endpoints
PI server:
Allowed value: any string
Default: null

ClientId Required for string The client ID used for authentication with an
OCS endpoints OSIsoft Cloud Services OMF endpoint

Allowed value: any string

Default: null

ClientSecret Required for string The client secret used for authentication with an
OCS endpoints OSIsoft Cloud Services OMF endpoint

Allowed value: any string

Default: null

TokenEndpoint Optional for string Retrieves an OCS token from an alternative

OCS endpoints endpoint

Allowed value: well-formed http or https endpoint

string
Default value: null

ValidateEndpointCertificate Optional boolean Disables verification of destination security

certificate. Use for testing only with self-signed
certificates; OSIsoft recommends keeping this set
to the default, true, in production environments.

Allowed value: true or false

Default value: true

93 PI Adapter for MQTT Published: 19 July 2022

 Examples
OCS endpoint

{
"Id": "OCS",
"Endpoint": "https://<OCS OMF endpoint>",
"ClientId": "<clientid>",
"ClientSecret": "<clientsecret>"
}

PI Web API endpoint

{
"Id": "PI Web API",
"Endpoint": "https://<pi web api server>:<port>/piwebapi/omf/",
"UserName": "<username>",
"Password": "<password>"
}

Note: When you use an adapter with a PI Web API health endpoint, the AF structure is required. If the
elements are deleted, the adapter recreates the elements; if the account used to authenticate to the PI Web
API has its permissions removed on the AF Server, the adapter retries sending health data to the PI Web API
until the permissions are restored.

REST URLs
Relative URL HTTP verb Action

api/v1/configuration/system/ GET Gets all configured health endpoints

healthEndpoints

api/v1/configuration/system/ DELETE Deletes all configured health endpoints

healthEndpoints

api/v1/configuration/system/ POST Adds an array of health endpoints or a single endpoint.

healthEndpoints Fails if any endpoint already exists

api/v1/configuration/system/ PUT Replaces all health endpoints. Note: Requires an array of

healthEndpoints endpoints

94 PI Adapter for MQTT Published: 19 July 2022

 Relative URL HTTP verb Action

api/v1/configuration/system/ PATCH Allows partial updating of configured health endpoints

healthEndpoints Note: The request must be an array containing one or
more health endpoints. Each health endpoint in the array
must include its Id.

api/v1/configuration/system/ GET Gets configured health endpoint by Id

healthEndpoints/Id

api/v1/configuration/system/ DELETE Deletes configured health endpoint by Id

healthEndpoints/Id

api/v1/configuration/system/ PUT Updates or creates a new health endpoint with the

healthEndpoints/Id specified Id

api/v1/configuration/system/ PATCH Allows partial updating of configured health endpoint by

healthEndpoints/Id Id

Note: Replace Id with the Id of the health endpoint.

Configuration examples
The following tables provide examples for all configurations available for PI Adapter for MQTT.

Note: The examples in this topic are using the default port number 5590. If you selected a different port
number, replace it with that value.TEST

System components configuration with two MQTT adapter

instances

[
{
"componentId": "OmfEgress",
"componentType": "OmfEgress"
},
{
"componentId": "MQTT1",
"componentType": "MQTT"
},
{
"componentId": " MQTTSparkplugB1",
"componentType": "MQTTSparkplugB"

95 PI Adapter for MQTT Published: 19 July 2022

 }
]

MQTT adapter configuration

{
"Mqtt1": {
"Logging": {
"logLevel": "Information",
"logFileSizeLimitBytes": 34636833,
"logFileCountLimit": 31
},
"DataSource": {
"StreamIdPrefix" : null,
"DefaultStreamIdPattern" : "{Topic}.{ValueField}",
"HostNameOrIpAddress" : "125.0.0.0",
"Port" : 8765,
"Protocol" : "Tcp",
"TLS" : "Tls12",
"UserName": null,
"Password": null,
"ClientId" : "Test-Cliendt-Id",
"MQTTVersion" : "3.1.1",
"ValidateServerCertificate" : true
},
"DataSelection": [
{
"Selected" : true,
"Name" : null,
"StreamId" : "RandomStreamId",
"DataFilterId" : null,
"Topic" : "RandomTopic",
"ValueField" : "$.TestNode[:1].Value",
"IndexField" : "$.TestNode[:1].Time",
"DataType" : "uint64",
"IndexFormat" : null
}
]
},
"System": {

96 PI Adapter for MQTT Published: 19 July 2022

 "Logging": {
"logLevel": "Information",
"logFileSizeLimitBytes": 34636833,
"logFileCountLimit": 31
},
"HealthEndpoints": [
],
"Diagnostics": {
"enableDiagnostics": true
},
"Components": [
{
"componentId": "Egress",
"componentType": "OmfEgress"
},
{
"componentId": "Mqtt1",
"componentType": "MQTT"
}
],
"Buffering": {
"BufferLocation": "C:/ProgramData/OSIsoft/Adapters/MQTT/Buffers",
"MaxBufferSizeMB": -1,
"EnableBuffering": true
}
},
"OmfEgress": {
"Logging": {
"logLevel": "Information",
"logFileSizeLimitBytes": 34636833,
"logFileCountLimit": 31
},
"DataEndpoints": [
{
"id": "WebAPI EndPoint",
"endpoint": "https://PIWEBAPIServer/piwebapi/omf",
"userName": "USERNAME",
"password": "PASSWORD"
},
{
"id": "OCS Endpoint",

97 PI Adapter for MQTT Published: 19 July 2022

 "endpoint": "https://OCSEndpoint/omf",
"clientId": "CLIENTID",
"clientSecret": "CLIENTSECRET"
}
]
}
}

Data source configuration

The following are representations of minimal and complete data source configurations of MQTT adapter.

MQTT (generic) - Minimal data source configuration

{
"HostNameOrIpAddress" : "125.0.0.0" ,
"Port" : 8765
}

MQTT (generic) - Complete data source configuration

{
"StreamIdPrefix" : null,
"DefaultStreamIdPattern" : "{Topic}.{ValueField}",
"HostNameOrIpAddress" : "125.0.0.0",
"Port" : 8765,
"Protocol" : "Tcp",
"TLS" : "Tls12",
"UserName": null,
"Password": null,
"ClientId" : "Test-Cliendt-Id",
"MQTTVersion" : "3.1.1",
"ValidateServerCertificate" : true
}

98 PI Adapter for MQTT Published: 19 July 2022

 MQTT Sparkplug B - Minimal data source configuration

{
"HostNameOrIpAddress" : "Host1",
"Port" : 4321,
}

MQTT Sparkplug B - Complete data source configuration

{
"HostNameOrIpAddress" : "Host1",
"Port" : 4321,
"PrimaryHostId" : "Optimus",
"Protocol" : "Tcp",
"TLS" : "Tls12",
"UserName" : "RandomUser",
"PassWord" : "RandomPassword",
"ClientId" : "Random-Client-Id",
"MQTTVersion" : "3.1.1",
"ValidateServerCertificate" : true,
"StreamIdPrefix" : null,
"DefaultStreamIdPattern" : "{PointId}"
}

Client settings configuration

{
"KeepAlivePeriod" : true,
"QosLevel" : 2,
"MaxInternalQueueSize" : 350000
}

Data selection configuration

The following are representations of minimal and complete data selection configurations of MQTT adapter.

99 PI Adapter for MQTT Published: 19 July 2022

 MQTT (generic) - Minimal data selection configuration

[
{
"Topic" : "RandomTopic",
"ValueField" : "$.TestNode[:1].Value",
"DataType" : "uint64"
}
]

MQTT (generic) - Complete data selection configuration

[
{ "Selected" : true,
"Name" : null,
"StreamId" : "RandomStreamId",
"DataFilterId" : null,
"Topic" : "RandomTopic",
"ValueField" : "$.TestNode[:1].Value",
"IndexField" : "$.TestNode[:1].Time",
"DataType" : "uint64",
"IndexFormat" : null
}
]

MQTT Sparkplug B - Minimal data selection configuration

[
{
"Topic" : "Home/Sensors",
"PropertyName" : "Temperature"
}
]

MQTT Sparkplug B - Complete data selection configuration

[
{

100 PI Adapter for MQTT Published: 19 July 2022

 "Selected" : true,
"Name" : "Temperature",
"Topic" : "Home/Sensors",
"PropertyName" : "temperature",
"StreamId" : "RandomStreamId",
"DataFilterId" : null
}
]

101 PI Adapter for MQTT Published: 19 July 2022

 Administration
With the PI adapter administration level functions, you can start and stop an adapter service and the
individual adapter ingress components. You can also retrieve product version information and delete an
adapter.

The examples in the administration topics use curl, a commonly available tool on both Windows and
Linux. You can use the same operations with any programming language or tool that supports making REST
calls. You can also configure PI adapters with the EdgeCmd utility. For more information, see the EdgeCmd
utility documentation. To validate successful configurations, you can accomplish data retrieval steps (GET
commands) using a browser, if available on your device.

For more information on PI adapter configuration tools, see Configuration tools.

102 PI Adapter for MQTT Published: 19 July 2022

 Start and stop an adapter
Complete the procedure appropriate for your operating system to start or stop an adapter service:

Windows
1. Open Windows services.

2. Select PI Adapter for <AdapterName>.

3. Depending on whether your adapter is running or not, click either Start or Stop.

Linux
1. Open command line.

2. Depending on whether your adapter is running or not, type one of the following commands:

Example:

Start PI Adapter for <AdapterName>

sudo systemctl start pi.adapter.<adapterName>

Example:

Stop PI Adapter for <AdapterName>

sudo systemctl stop pi.adapter.<adapterName>

3. Press Enter.

Start and stop ingress component

To control data ingress, you can start and stop the ingress components of an adapter whenever necessary.
By default, all currently configured ingress components are started.

Start an ingress component

Complete the following steps to start an individual ingress component:

1. Use any of the Configuration tools capable of making HTTP requests.

103 PI Adapter for MQTT Published: 19 July 2022

 2. Run a POST command to the following endpoint, replacing <ComponentId> with the ingress
component that you want to start: http://localhost:5590/api/v1/administration/
<ComponentId>/Start

Note: 5590 is the default port number. If you selected a different port number, replace it with that
value.

Example using curl:

Start the adapter ingress component

curl -d "" -X POST "http://localhost:5590/api/v1/Administration/<ComponentId>/Start"

Stop an ingress component

Complete the following steps to stop an individual ingress component:

1. Start any configuration tool capable of making HTTP requests.

2. Run a POST command to the following endpoint, replacing <ComponentId> with the ingress
component that you want to stop: http://localhost:5590/api/v1/administration/
<ComponentId>/Stop

Note: 5590 is the default port number. If you selected a different port number, replace it with that
value.

Example using curl:

Stop the adapter ingress component

curl -d "" -X POST "http://localhost:5590/api/v1/Administration/<ComponentId>/Stop"

Delete an adapter component

When you remove an adapter component, the configuration and log files are saved into a sub-directory in
case they are needed later. Any associated types, streams, and data remain on the respective endpoints.

Complete the following steps to delete an adapter component:

1. Start any of the Configuration tools capable of making HTTP requests.

104 PI Adapter for MQTT Published: 19 July 2022

 2. Run a DELETE command to the following endpoint: http://localhost:5590/api/v1/
configuration/system/components/<ComponentId>

Note: You must make an empty DELETE command against the Id of the component you want to
delete.
5590 is the default port number. If you selected a different port number, replace it with that value.

Example using curl :

Delete an adapter component

curl -X DELETE "http://localhost:5590/api/v1/configuration/system/components/<ComponentId

>"

File relocation
All configuration and log files are renamed and moved. The files are renamed according to the timestamp of
removal, for example, FileName.json_removed_yyyy-MM-dd--hh-mm-ss.

Configuration files are moved to the following location:

Windows: %programdata%\OSIsoft\Adapters\AdapterName\Configuration\Removed

Linux: /usr/share/OSIsoft/Adapters/AdapterName/Configuration/Removed

Log files are moved to the following location:

Windows: %programdata%\OSIsoft\Adapters\AdapterName\Logs\Removed

Linux: /usr/share/OSIsoft/Adapters/AdapterName/Logs/Removed

In the following example, one adapter service is installed on a particular Windows node with the name
<Adapter>Service1. An adapter component with the name <Adapter>DeviceX was added and
configured to this adapter and later removed. Linux follows a similar behavior. This is the resulting
relocation and renaming scheme after deletion:

105 PI Adapter for MQTT Published: 19 July 2022

 REST URLs
Relative URL HTTP verb Action

api/v1/configuration/system/components/ComponentId DELETE Deletes specified component

106 PI Adapter for MQTT Published: 19 July 2022

 Note: Replace ComponentId with the Id of the component that you want to delete.

Retrieve product version information

The product version information includes the adapter framework version, application version, the version of
the underlying .NET Core framework, and the operating system that the adapter is running on.

Complete the following steps to retrieve the product version information of a PI adapter:

1. Use any of the Configuration tools capable of making HTTP requests.

2. Run a GET command to the following endpoint: http://localhost:5590/api/v1/

Diagnostics/ProductInformation

Note: 5590 is the default port number. If you selected a different port number, replace it with that
value.

Example using curl:

Get product information for adapter hosted on port 5590

curl -X GET "http://localhost:5590/api/v1/Diagnostics/ProductInformation"

Example result:

{
"Application Name": "PI Adapter for <AdapterName>",
"Adapter Framework Version": "1.3.0.351",
"Application Version":"1.2.0.37",
".Net Core Version":".NET Core 3.1.5",
"Operating System":"Linux 4.15.0-106-generic #107-Ubuntu SMP Thu Jun 4 11:27:52 UTC 2020"
}

107 PI Adapter for MQTT Published: 19 July 2022

 Health and Diagnostics
PI Adapters produce various types of health data. You can use health data to ensure that your adapters are
running properly and that data flows to the configured OMF endpoints. For more information on available
adapter health data, see health.

PI Adapters also produce diagnostic data. You can use diagnostic data to find more information about a
particular adapter instance. Diagnostic data lives alongside the health data and you can egress it using a
health endpoint and setting EnableDiagnostics totrue. You can configure EnableDiagnostics in
the system's General configuration. For more information on available adapter diagnostics data, see
diagnostics.

In OSIsoft Cloud Services (OCS), both health and diagnostics data are created as assets. The data are
available in the Asset Explorer and you can use them in the OCS Trend feature. For more information, see
the OCS documentation Assets.

Health endpoint differences

Two OMF endpoints are currently supported for adapter health data:

• PI Web API

• OSIsoft Cloud Services (OCS)

There are a few differences in how these two systems treat the associated health and diagnostics data.

• PI Web API parses the information and sends it to configured PI servers for the OMF endpoint. The
static data is used to create an AF structure on a PI AF server. The dynamic health data is time-series
data that is stored in PI points on a PI Data Archive. You can see it in the AF structure as PI point data
reference attributes.

• OCS does not currently provide a way to store the static metadata. For OCS-based adapter health
endpoints, only the dynamic data is stored. Each value is its own stream with the timestamp property
as the single index.

AF structure
With a health endpoint configured to a PI server, you can use PI System Explorer to view the health and
diagnostics of an adapter. The element hierarchy is shown in the following image.

108 PI Adapter for MQTT Published: 19 July 2022

 • The Elements root contains a link to an Adapters node. This is the root node for all adapter instances.

• Below Adapters, you will find one or more adapter nodes. Each node's title is defined by the node's
corresponding computer name and service name in this format: {ComputerName}.
{ServiceName}. For example, in the following image, MachineName is the computer name and
OpcUa is the service name.

• To see the health and diagnostics values, click on an adapter node and select Attributes.

109 PI Adapter for MQTT Published: 19 July 2022

 Health
PI Adapters produce various kinds of health data that can be egressed to different health endpoints.

To egress health related data, you have to configure an adapter health endpoint first. See Health endpoint
configuration.

Available health data

Dynamic data is sent every minute to configured health endpoints.

The following health data is available:

• Device status

• Next Health Message Expected

Device status
The device status indicates the health of this component and if it is currently communicating properly with
the data source. This time-series data is stored within a PI point or OCS stream, depending on the endpoint
type. During healthy steady-state operation, a value of Good is expected.

Property Type Description

Time string Timestamp of the event

DeviceStatus string The value of the DeviceStatus

The possible statuses are:

Status Meaning

Good The component is connected to the data source and it is collecting data.

ConnectedNoData The component is connected to the data source but it is not receiving data from it.

Starting The component is currently in the process of starting up and is not yet connected to the
data source.

DeviceInError The component encountered an error either while connecting to the data source or
attempting to collect data.

Shutdown The component is either in the process of shutting down or has finished.

110 PI Adapter for MQTT Published: 19 July 2022

 Status Meaning

Removed The adapter component has been removed and will no longer collect data.

NotConfigured The adapter component has been created but is not yet configured.

Next health message expected

This property is similar to a heartbeat. A new value for NextHealthMessageExpected is sent by an
individual adapter data component on a periodic basis while it is functioning properly. This value is a
timestamp that indicates when the next value should be received. When monitoring, if the next value is not
received by the indicated time, this likely means that there is an issue. It could be an issue with the adapter,
adapter component, network connection between the health endpoint and the adapter, and so on.

Property Type Description

Time string Timestamp of the event

NextHealthMessageExpected string Timestamp when next value is expected

Diagnostics
The adapter and its components produce various kinds of diagnostics data that is sent to all health
endpoints. The System_Diagnostics.json file contains a flag that determines whether diagnostics
are enabled. You can change this at runtime through REST calls or the EdgeCmd utility. Diagnostics data are
collected by default.

To egress diagnostics related data, you have to configure an adapter health endpoint first. See Health
endpoint configuration.

Available diagnostics data

Every minute, dynamic data is sent to configured health endpoints.

The following diagnostics data are available:

• System

• Stream count

• IO rate

111 PI Adapter for MQTT Published: 19 July 2022

 • Error rate

System
The Diagnostics.System dynamic type includes the following values which are logged in a stream with
the Id System.Diagnostics. This diagnostic stream contains system level information related to the
host platform that the adapter is running on.

Property Type Description

timestamp  string Timestamp of event 

ProcessIdentifier  int Process Id of the host process 

StartTime  string Time at which the host process started 

WorkingSet  long Amount of physical memory in bytes, allocated for the host process 

TotalProcessorTime  double Total processor time for the host process expressed in seconds 

TotalUserProcessorTime double User processor time for the host process expressed in seconds 

TotalPrivilegedProcessorTime double Privileged processor time for the host process expressed in seconds 

ThreadCount int Number of threads in the host process

HandleCount  int Number of handles opened by the host process 

ManagedMemorySize  double Number of bytes currently thought to be allocated in managed

memory
Unit of Measure = megabytes 

PrivateMemorySize  double Amount of paged memory in bytes allocated for the host process
Unit of Measure = megabytes 

PeakPagedMemorySize  double Maximum amount of memory in the virtual memory paging file in
bytes used by the host process.
Unit of Measure = megabytes

StorageTotalSize  double Total size of the storage medium in use by the system
Unit of Measure = megabytes 

StorageFreeSpace  double Free space available

Unit of Measure = megabytes 

112 PI Adapter for MQTT Published: 19 July 2022

 Each adapter component produces its own diagnostics streams.

Stream count
The Diagnostics.StreamCountEvent dynamic type includes the following values, which are logged
in a stream with the Id {componentid}.StreamCount. The StreamCount and TypeCount include
only types and streams created for sequential data received from a data source.

Property Type Description

timestamp string Timestamp of event

StreamCount int Number of streams created by the adapter instance

TypeCount int Number of types created by the adapter instance

IO rate
The Diagnostics.Adapter.IORate dynamic type includes the following values, which are logged in a
stream with the Id {componentid}.IORate. IORate includes only sequential data collected from a
data source.

Property Type Description

timestamp string Timestamp of event

IORate double One-minute rolling average of data rate (streams/second)

Error rate
The Diagnostics.Adapter.ErrorRate dynamic type includes the following values, which are
logged in a stream with the Id {componentid}.ErrorRate.

Property Type Description

timestamp string Timestamp of event

113 PI Adapter for MQTT Published: 19 July 2022

 Property Type Description

ErrorRate double One-minute rolling average of error rate (streams/second)

Egress
The Egress component of the adapter produces the following diagnostics stream:

IO rate
The Diagnostics.Egress.IORate dynamic type includes the following values, which are logged in a
stream with the Id {machineName}.{serviceName}.OmfEgress.{EndpointId}.IORate.
IORate includes only sequential data successfully sent to an egress endpoint.

Property Type Description

timestamp string Timestamp of event

IORate double One-minute rolling average of data rate (streams/second)

114 PI Adapter for MQTT Published: 19 July 2022

 Troubleshooting
PI adapters provide features for troubleshooting issues related to connectivity, data flow, and configuration.
Resources include adapter logs and the Wireshark troubleshooting tool . If you are still unable to resolve
issues or need additional guidance, contact OSIsoft Technical Support through the OSIsoft Customer Portal.

Note: Make sure to also check the troubleshooting information specific to your adapter in this user guide.

Logs
Messages from the System and OmfEgress logs provide information on the status of the adapter. For
example, they show if a connection from the adapter to an egress endpoint exists.

Perform the following steps to view the System and OmfEgress logs:

1. Navigate to the logs directory:

Windows: %ProgramData%\OSIsoft\Adapters\<AdapterName>\Logs
Linux: /usr/share/OSIsoft/Adapters/<AdapterName>/Logs.

Example:
A successful connection to a PI Web API egress endpoint displays the following message in the
OmfEgress log:

2020-11-02 11:08:51.870 -06:00 [Information] Data will be sent to the following OMF endpoint:
Id: <omfegress id>
Endpoint: <pi web api URL> (note: the pi web api default port is 443)
ValidateEndpointCertificate: <true or false>

2. Optional: Change the log level of the adapter to receive more information and context. For more
information, see Logging configuration.

ASP .NET Core platform log

The ASP .NET Core platform log provides information from the Kestrel web server that hosts the
application. The log could contain information that the adapter is overloaded with incoming data. Perform
the following steps to spread the load among multiple adapters:

1. Decrease the scan frequency.

2. Lower the amount of data selection items.

Wireshark
Wireshark is a protocol-specific troubleshooting tool that supports all current adapter protocols. Perform
the following steps if you want to use Wireshark to capture traffic from the data source to the adapter or
from the adapter to the OMF destination.

115 PI Adapter for MQTT Published: 19 July 2022

 1. Download Wireshark.
2. Familiarize yourself with the tool and read the Wireshark user guide.

Health and diagnostics egress to PI Web API

The adapter sends health and diagnostics data to PI Web API; in some cases, conflicts may occur that are
due to changes or perceived changes in PI Web API. For example, a 409 - Conflict error message
displays if you upgrade your adapter version and the PI points do not match in the upgraded version.
However, data is continued to be sent as long as containers are created, so buffering only starts if no
containers are created.

To resolve the conflict, perform the following steps:

1. Stop the adapter.

2. Delete the Health folder inside of the Buffers folder.
3. Stop PI Web API.
4. Delete the relevant adapter created AF structure.
5. Delete the associated health and diagnostics PI points on any or all PI Data Archives created by PI Web
API.
6. Start PI Web API.
7. Start the adapter.

Adapter connection to egress endpoint

Certain egress health information in both PI Web API and OCS show if an adapter connection to an egress
endpoint exists. To verify an active connection, perform one of the following procedures:

PI Web API connection

Perform the following steps to determine if a connection to the PI Web API endpoint exists:

1. Open PI Web API.

2. Select the OmfEgress component of your adapter, for example
GVAdapterUbuntu.<AdapterName>.OmfEgress.
3. Make sure that the following PI points have been created for your egress endpoint:
• DeviceStatus

• NextHealthMessageExpected

• IORate

OCS connection
Perform the following steps to determine if a connection to the OCS endpoint exists:

1. Open OCS.
2. Click Sequential Data Store > Streams.
3. Makes sure that the following streams have been created for your egress endpoint:
• DeviceStatus

116 PI Adapter for MQTT Published: 19 July 2022

 • NextHealthMessageExpected

• IORate

TCP connection
Perform the following steps to see all established TCP sessions in Linux:

1. Open a terminal.
2. Type the following command: ss -o state established -t -p
3. Press Enter.

117 PI Adapter for MQTT Published: 19 July 2022

 Troubleshoot PI Adapter for MQTT
PI Adapter for MQTT provides troubleshooting features that enable you to verify adapter configuration,
confirm connectivity, and view message logs. If you are unable to resolve issues with the adapter or need
additional guidance, contact OSIsoft Technical Support through the OSIsoft Customer Portal.

Check configurations
Incorrect configurations can interrupt data flow and cause errors in values and ranges. Perform the following
steps to confirm correct configuration for your adapter.

1. Navigate to data source configuration and verify the following for each configured data source item
below:

• HostNameOrIpAddress - The correct host name or IP address of the MQTT server is

referenced. A non-existent or incorrect HostNameOrIpAddress causes the adapter to not find
the MQTT server.

• Port - The correct port number is referenced. With an incorrect port number specified, the
adapter cannot communicate to the MQTT server.

• Protocol - The correct protocol is referenced. With an incorrect Protocol specified, the adapter
cannot communicate to the MQTT broker.

• TLS - The supported TLS (Transport Layer Security) is used.

• MQTTVersion - The correct MQTTVersion is referenced.

• ValidateServerCertificate - If enabled (and TLS is enabled), the adapter validates the server
certificate. When the server certificate is not trusted, you can either add it to the OS certificate
store or set ValidateServerCertificate to false.

2. Navigate to data selection configuration and verify that the following data selection items are correct:

For the MQTT Sparkplug B component:

• Topic - The topic string is valid. An incorrect topic string causes the adapter to not receive any
values for this data selection item.

• MetricName - The metric name string is valid. With an incorrect metric name, the adapter
cannot extract a data value from the MQTT server payload.

For the generic MQTT component:

• ValueField - The JsonPath expression is valid. With an invalid JsonPath expression, the adapter
cannot extract a data value from the MQTT server payload.

• IndexField - The JsonPath expression is valid. With an invalid JsonPath expression, the adapter
cannot extract a timestamp from the MQTT server payload.

118 PI Adapter for MQTT Published: 19 July 2022

 • DataType - The correct data type is referenced. An incorrect data type causes data conversion
to fail.

• IndexFormat - The correct time format is referenced. A time format that does not match the
value from IndexField means that the adapter cannot convert timestamp from the MQTT
server payload.

3. Navigate to egress endpoints configuration. For each configured endpoint, verify that the Endpoint
and authentication properties are correct.

• For a PI server endpoint, verify UserName and Password.

• For an OCS endpoint, verify ClientId and ClientSecret.

Check connectivity
Perform the following steps to verify active connections to the data source and egress endpoints.

1. Start PI Web API and verify that the PI point values are updating or start OCS and verify that the
stream values are updating.
2. If configured, use a health endpoint to determine the status of the adapter.
For more information, see Health and diagnostics.

Check logs
Perform the following steps to view the adapter and endpoint logs to isolate issues for resolution.

1. Navigate to the logs directory:

Windows: %ProgramData%\OSIsoft\Adapters\MQTT\Logs
Linux: /usr/share/OSIsoft/Adapters/MQTT/Logs.
2. Optional: Change the log level of the adapter to receive more information and context.
For more information, see Logging configuration.

119 PI Adapter for MQTT Published: 19 July 2022

 Release notes
PI Adapter for MQTT 1.1.0.114
Adapter framework 1.5

Overview
PI Adapter for MQTT collects time-series data from MQTT servers, its service nodes/devices adhering to the
SparkplugB specification, but also generic producing JSON payload. It then sends the data to configured
OMF endpoints such as PI Web API and OSIsoft Cloud Services.

PI Adapter for MQTT is capable of collecting health and diagnostics information. It supports buffering,
unsolicited data collection, automatic discovery of available data items on a SparkplugB data source, various
Windows and Linux-based operating systems, and containerization.

For more information see PI Adapter for MQTT overview.

Fixes and enhancements

This updated release contains bug fixes and adapter framework updates.

Fixes
The following items were resolved in release 1.1.0.114:

Item Description

313786 The issue related to parsing DBIRTH messages causing data loss on startup is fixed.

318285 The issue related to parsing multilevel wildcards has been fixed.

Known issues
There are no known issues at this time.

Setup
System requirements
Refer to System requirements.

Installation and upgrade

Refer to Install the adapter.

120 PI Adapter for MQTT Published: 19 July 2022

 Uninstallation
Refer to Uninstall the adapter.

Security information and guidance

OSIsoft's commitment
Because the PI System often serves as a barrier protecting control system networks and mission-critical
infrastructure assets, OSIsoft is committed to (1) delivering a high-quality product and (2) communicating
clearly what security issues have been addressed. This release of PI Adapter for MQTT is the highest quality
and most secure version of the PI Adapter for MQTT released to date. OSIsoft's commitment to improving
the PI System is ongoing, and each future version should raise the quality and security bar even further.

Vulnerability communication
The practice of publicly disclosing internally discovered vulnerabilities is consistent with the Common
Industrial Control System Vulnerability Disclosure Framework developed by the Industrial Control Systems
Joint Working Group (ICSJWG). Despite the increased risk posed by greater transparency, OSIsoft is sharing
this information to help you make an informed decision about when to upgrade to ensure your PI System
has the best available protection.

For more information, refer to OSIsoft's Ethical Disclosure Policy (https://www.osisoft.com/ethical-

disclosure-policy).

To report a security vulnerability, refer to OSIsoft's Report a Security Vulnerability (https://www.osisoft.com/

report-a-security-vulnerability).

Vulnerability scoring
OSIsoft has selected the Common Vulnerability Scoring System (CVSS) to quantify the severity of security
vulnerabilities for disclosure. To calculate the CVSS scores, OSIsoft uses the National Vulnerability Database
(NVD) calculator maintained by the National Institute of Standards and Technology (NIST). OSIsoft uses
High, Medium and Low categories to aggregate the CVSS Base scores. This removes some of the opinion-
related errors of CVSS scoring. As noted in the CVSS specification, Base scores range from 0 for the lowest
severity to 10 for the highest severity.

Overview of new vulnerabilities found or fixed

This section is intended to provide relevant security-related information to guide your installation or
upgrade decision. OSIsoft is proactively disclosing aggregate information about the number and severity of
PI Adapter for MQTT security vulnerabilities that are fixed in this release.

No security-related information is applicable to this release.

121 PI Adapter for MQTT Published: 19 July 2022

 Technical support and resources
Refer to Technical support and feedback.

Technical support and feedback

OSIsoft provides several ways to report issues and provide feedback on PI Adapters.

Technical support
For technical assistance with PI Adapters, contact OSIsoft Technical Support through the OSIsoft Customer
Portal. We can help you identify the problem, provide workarounds and address any concerns you may have.
Remote access to your facilities may be necessary during the session.

Note: You must have an account set up in the OSIsoft Customer Portal before you can open a case. If you do
not have a portal account, see How to Get a Login to OSIsoft Customer Portal.

Alternatively, call OSIsoft Technical Support at +1 510-297-5828.

When you contact OSIsoft Technical Support, be prepared to provide this information:

• Product name, version, and build numbers

• Details about your computer platform (CPU type, operating system, and version number)

• Time that the difficulty started

• Log files at that time

• Details of any environment changes prior to the start of the issue

• Summary of the issue, including any relevant log files during the time the issue occurred

Product feedback
To submit product feedback for PI Adapters, visit the PI Adapters feedback page. The product team at
OSIsoft regularly monitors the page.

Documentation feedback
To submit documentation feedback for PI Adapters, send an email to [email protected]. Be sure
to include the following information with your feedback:

• Product name and version

• Documentation topic URL

122 PI Adapter for MQTT Published: 19 July 2022

 • Details of the suggestion or error

The technical documentation team will review and address your feedback in future documentation updates.

123 PI Adapter for MQTT Published: 19 July 2022

124 PI Adapter for MQTT Published: 19 July 2022