XL3 API Manual
4 July, 2024

NTi Audio, Im alten Riet 102, 9494 Schaan, LiechtensteinXL3 API Manual

Preamble................................................................................................................................................... 6
Quick Start ........................................................................................................................................................ 7
How to connect the XL3 physically................................................................................................................. 8
Worldwide Access - NTi Connect.................................................................................................................... 8
Communication Protocols .............................................................................................................................. 9
TCP ............................................................................................................................................................9
WebSockets ..............................................................................................................................................9
Communication - First steps ......................................................................................................................... 10First Prompt............................................................................................................................................ 10
Identification Message (Advanced Streaming) ................................................................................... 10
Basic Code examples (Python 3.8)............................................................................................................... 11
TCP ............................................................................................................................................................9
WebSocket ............................................................................................................................................. 12
NTi Connect............................................................................................................................................ 13
Streaming API ......................................................................................................................................... 14
Basic Streaming API ...................................................................................................................................... 14
Introduction ............................................................................................................................................ 14
Communication...................................................................................................................................... 15
Command ........................................................................................................................................15
Answer.............................................................................................................................................15
Example: 123 values .......................................................................................................................16
Example: 123 and spectrum values...............................................................................................17
Python example ..................................................................................................................................... 18
Advanced Streaming API............................................................................................................................... 19
Introduction ............................................................................................................................................ 19
Configuring the XL3 ............................................................................................................................... 19
Typical configuration file................................................................................................................20
Important Settings for Streaming ..................................................................................................21
Data Stream Channels........................................................................................................................... 23
Channels ID .....................................................................................................................................23
Content ID........................................................................................................................................23
Channel states ................................................................................................................................24
XL3 Message format ......................................................................................................................24
SYSTEM Channel ............................................................................................................................25

www.nti-audio.com

Page 2

XL3 API Manual

SPLLOG Channel.............................................................................................................................27
SPLREP Channel .............................................................................................................................31
AUDIO Channel................................................................................................................................34
SOH Channel ...................................................................................................................................36
WEATHER Channel .........................................................................................................................38
Using multiple channels ........................................................................................................................ 39… on the same WebSocket .................................................................................................................... 39… on different WebSockets ................................................................................................................... 40
Control API.............................................................................................................................................. 41
Introduction .................................................................................................................................................... 41
Command Structure ...................................................................................................................................... 41
Command Format.................................................................................................................................. 41
Command Responses ........................................................................................................................... 42
Error Queue............................................................................................................................................. 42
Multiple Commands .............................................................................................................................. 42
Timeouts................................................................................................................................................. 42
Command-List................................................................................................................................................ 43
Device Status ......................................................................................................................................... 43*IDN?................................................................................................................................................43*CLS .................................................................................................................................................43*RST .................................................................................................................................................44
INITiate Subsystem................................................................................................................................ 45
INITiate ............................................................................................................................................45
INITiate:STATe? ..............................................................................................................................45
MEASure Subsystem ............................................................................................................................. 46
MEASure:INITiate............................................................................................................................46
MEASure:TIMer? .............................................................................................................................46
MEASure:TIMer:MODE....................................................................................................................47
MEASure:TIMer:MODE?..................................................................................................................47
MEASure:TIMer:SET:SINGle ...........................................................................................................47
MEASure:TIMer:SET:SINGle? .........................................................................................................48
MEASure:TIMer:SET:REPEated ......................................................................................................48
MEASure:TIMer:SET:REPEated? ....................................................................................................49
MEASure:FUNCtion.........................................................................................................................49

www.nti-audio.com

Page 3

XL3 API Manual

MEASure:FUNCtion? .......................................................................................................................49
MEASure:DECImals.........................................................................................................................50
MEASure:DECImals?.......................................................................................................................50
MEASure: SLM Subsystem.................................................................................................................... 51
MEASure:SLM:123? ........................................................................................................................51
MEASure:SLM:123:DT?...................................................................................................................53
MEASure:SLM:SPECtrum? .............................................................................................................55
MEASure:SLM:SPECtrum:DT?........................................................................................................56
MEASure:SLM:SPECtrum:RESolution ............................................................................................57
MEASure:SLM:SPECtrum:RESolution? ..........................................................................................57
MEASure:SLM:SPECtrum:WEIGhting.............................................................................................58
MEASure:SLM:SPECtrum:WEIGhting?...........................................................................................58
MEASure:RT60 Subsystem ................................................................................................................... 59
MEASure:RT60? ..............................................................................................................................59
MEASure:RT60:ATTR? ....................................................................................................................60
MEASure:RT60:RESolution.............................................................................................................61
MEASure:RT60:RESolution? ...........................................................................................................61
MEASure:RT60:TRIGger:LEVel:MINimum .....................................................................................62
MEASure:RT60:TRIGger:LEVel:MINimum?....................................................................................62
INPut Subsystem ................................................................................................................................... 63
INPut:PHANtom ..............................................................................................................................63
INPut:PHANtom? ............................................................................................................................63
CALIbrate Subsystem ............................................................................................................................ 64
CALIbrate:MICrophone:TYPE? .......................................................................................................64
CALIbrate:MICrophone:SERIal?......................................................................................................64
CALIbrate:MICrophone:SENSitivity:VALUe?..................................................................................64
CALIbrate:MICrophone:CIC ............................................................................................................65
CALIbrate:MICrophone:TEMPerature? ..........................................................................................65
SYSTem Subsystem .............................................................................................................................. 66
SYSTem:CONFiguration:JStream ..................................................................................................66
SYSTem:CONFiguration:JStream? ................................................................................................66
SYSTem:CONFiguration:JStream:ERRor:TEXT? ...........................................................................67
SYSTem:CONFiguration:JEncoded................................................................................................67
SYSTem:CONFiguration:JEncoded?..............................................................................................68
SYSTem:CONFiguration:FILE:LOAD...............................................................................................69

www.nti-audio.com

Page 4

XL3 API Manual

SYSTem:CONFiguration:DOCumentation......................................................................................70
SYSTem:FILE:WRITe .......................................................................................................................70
SYSTem:FILE:READ?.......................................................................................................................71
SYSTem:POWer:SOURce? ..............................................................................................................71
SYSTem:SOH?.................................................................................................................................72
SYSTem:OPTIons?..........................................................................................................................72
SYSTem:ERRor? ..............................................................................................................................73
Appendix ................................................................................................................................................. 75
Error List ......................................................................................................................................................... 75
List of symbols............................................................................................................................................... 82
Parameter Types............................................................................................................................................ 82
Differences between XL3 and XL2................................................................................................................ 83
Getting Started with Python and PyCharm Community Edition.................................................................. 84
Installing the Latest Python Version..................................................................................................... 84
Installing PyCharm Community Edition................................................................................................ 84
Opening an Existing Project in PyCharm .............................................................................................. 84
Configure the Project Interpreter: ......................................................................................................... 84
Adding the websocket-client Package ................................................................................................. 84
Running the Example Code ................................................................................................................... 85

www.nti-audio.com

Page 5

XL3 API Manual
Preamble

Preamble This document refers to XL3 firmware version 1.34 or higher
The XL3 is designed for easy integration into Noise Monitoring and measurement applications and offers thefollowing services:
Service

Description

Application

Basic Streaming API
Pushes the values seen on the 123 screen and the bar
spectrum to up to 20 clients.

Dashboards

Advanced Streaming API
Stream SPL (Sound Pressure Level), SOH (State of Health),
Weather and Audio for easy integration into Noise
Monitoring applications.

Noise Monitoring

Control API

Control and manually query SLM and RT measurements.

Test Systems

File Push Service

Push measurement results to Google Drive, SFTP or
WebDAV clients.

Various

SFTP

File access via an SSH connection (not to be confusedwith FTPS).

Special cases

Streaming API(Programming Interface) Option required API
You need the API (Programming Interface) Option installed on your XL3 to include- the Advanced Streaming and- the Control API
interface in your application.
The Basic Streaming API, File Push Service and SFTP access are available by default. Refer to the XL3 User
Manual for further details.

www.nti-audio.com

Page 6

XL3 API Manual
Preamble

Quick Start
1. Connect the XL3 with the supplied USB-C cable to your PC's USB port
2. Install MobaXterm free Home Edition PC software from https://mobaxterm.mobatek.net/
download.html
3. When the software runs, click

Start local terminal

4. In the MobaXterm terminal window, typenc xl3-usb.local 50312

5. Press ENTER when the password is requested
6. The response should be a message that identifies the XL3, for example:
XL3 Streaming API Text, A3A-00100-D0, 1.24

7. Enter the following command:
SOH

The response could be
2;3;1698139974358;60000;13;LocalTime|TimeZone|BatterySOC|RunStatus|
WeatherStations|VDcIn|IPhantom|FreeStorage|GpsLocation|Temperature|AirPressure|PowerSource|ClockSource;-|-|%|-|-|V|A|MB|deg|degC|hPa|-|3;3;1698139974398;2023-10-18 04:47:00|Europe/Berlin||Running|2|9.15|0.004|
1920.090||36.0|965.4|DcIn|NTP

A new SOH (State of Health) data message appears every 60 seconds.
Press CTRL+C to close the connection.

www.nti-audio.com

Page 7

XL3 API Manual
Preamble

How to connect the XL3 physically
The XL3 can communicate through the following interfaces:
Interface

XL3 Address

Comment

USB-C

IP-Address or xl3-usb.local

One XL3 per PC

WiFi / Ethernet

IP-Address or xl3-00100.local

Ethernet using USB to Ethernet Adapter

Worldwide Access - NTi Connect
The NTi Connect service https://connect.nti-audio.com provides worldwide and secure access to the
webpage, data files and APIs of XL3s.

 XL3 uses port 22 to communicate with the NTi Connect server
NTi Connect provides free usage for data volumes up to 2 GB per month. For data consumption beyond thisthreshold, the download speed will be reduced. Opting for the "NTi Connect Open Data 365" subscription
ensures uninterrupted communication at full speed. For comprehensive information, kindly consult the XL3User Manual.

www.nti-audio.com

Page 8

XL3 API Manual
PreambleCommunication Protocols
The APIs are available using the following communication protocols:

TCP
The APIs are available in a LAN over the following ports:
Service

TCP Port

Streaming API Advanced

50312, 50313

Streaming API Basic

not available

Control API

50300

Examplenc XL3-00228.local 50312
Password:
1234
XL3 Streaming API Text, A3A-00100-D0, 1.28

WebSockets
WebSockets use port 80/443 and are designed for communicating in WANs but are also available in LANs:
Service

WebSocket in a LAN

Streaming API

ws://xl3_ip_address/api/stream1/
ws://xl3_ip_address/api/stream2/
ws://xl3_ip_address/api/live/

Control API

ws://xl3_ip_address/api/control/

NTi Connect (see page 6) offers access to the API WebSockets from anywhere whenever an XL3 has access tothe internet:
Service

WebSocket on NTi Connect

Streaming API

wss://connect.nti-audio.com/ConnectKey/api/stream1/
wss://connect.nti-audio.com/ConnectKey/api/stream2/
wss://connect.nti-audio.com/ConnectKey/api/live/

Control API

wss://connect.nti-audio.com/ConnectKey/api/control/

www.nti-audio.com

Page 9

XL3 API Manual
PreambleCommunication - First steps
First Prompt
After a connection is established, the XL3 sends a first prompt, which could be:
PromptActionEnter password.

Password:

If the PW is wrong, the XL3 sends the message
Incorrect password and closes theconnection.

Comment
a direct USB-C
 For
connection, any
password will be
accepted.

Already in use
Offline

The connection is closed.
Retry to connect after some delay.

XL3 not found onconnect.nti-audio.com

Identification Message (Advanced Streaming)
After entering the correct password, the XL3 confirms with the interface identification message:nc XL3-00228.local 50312
Password:
1234
NTi Audio XL3 Streaming API Text, A3A-00100-D0, 1.28

The interface is now ready for commands, for example:
SOH
2;3;1699971038797;60000;13;LocalTime|TimeZone|BatterySOC|RunStatus|WeatherStations|
VDcIn|IPhantom|FreeStorage|GpsLocation|Temperature|AirPressure|PowerSource|
ClockSource;-|-|%|-|-|V|A|MB|deg|degC|hPa|-|3;3;1699971000157;2023-11-14 15:10:00|Europe/Berlin|100.0|Stopped|0|9.10|0.006|
29792.281||33.7|967.2|DcIn|NTP
3;3;1699971060157;2023-11-14 15:11:00|Europe/Berlin|100.0|Running|0|9.11|0.006|
29769.656||33.7|967.1|DcIn|NTP
3;3;1699971120157;2023-11-14 15:12:00|Europe/Berlin|100.0|Running|0|9.11|0.006|
29747.000||33.8|967.1|DcIn|NTP

www.nti-audio.com

Page 10

XL3 API Manual
Preamble

Basic Code examples (Python 3.8)
TCP
import socket
MyXL3 = "xl3-00100.local"# MyXL3 = "192.168.201.100"# MyXL3 = "xl3-usb.local"
XL3Password = b"1234"
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect((MyXL3, 50312))# use makefile to provide a readline to the socket
sockFile = sock.makefile(mode='r')
passwordPrompt = sockFile.readline()
sock.send(XL3Password+b'\n')print(sockFile.readline())
sock.send(b"SOH\n")while True:
print(sockFile.readline())

www.nti-audio.com# Identification Message# SOH header & results

Page 11

XL3 API Manual
Preamble

WebSocket
from websocket import create_connection# websocket --> install websocket-client# https://github.com/websocket-client/websocket-client
MyXL3 = "xl3-00100.local"# MyXL3 = "192.168.201.100"# MyXL3 = "xl3-usb.local"
XL3Password = b"1234"
url = "ws://" + MyXL3 + "/api/stream1/"
xl3 = create_connection(url)passwordPrompt = xl3.recv()xl3.send(XL3Password+b'\n')print(xl3.recv())
xl3.send(b"SOH\n")while True:
print(xl3.recv())

www.nti-audio.com# Identification Message# SOH header & results

Page 12

XL3 API Manual
Preamble

NTi Connect
from websocket import create_connection# websocket --> install websocket-client# https://github.com/websocket-client/websocket-client
ConnectKey = "ABCDE-FGHIJ"
XL3Password = b"1234"
url = "wss://connect.nti-audio.com/" + ConnectKey + "/api/stream1/"
xl3 = create_connection(url)passwordPrompt = xl3.recv()xl3.send((XL3Password+b'\n'))print(xl3.recv())
xl3.send(b"SOH\n")while True:
print(xl3.recv())# Identification Message# SOH header & results

SOH means “State of Health” and returns a result every 60 seconds. A detailed description follows later inthis document.

www.nti-audio.com

Page 13

XL3 API Manual
Streaming API

Streaming API
Basic Streaming API
Introduction
In the Sound Level Meter function, the XL3 can push the results of the 123 and spectrum screen in JSON
format to up to 20 clients. This API is used for the XLVIEW of the XL3 webpage but is not limited to that use
case.

www.nti-audio.com

Page 14

XL3 API Manual
Streaming API

Communication
After opening the connection to the API, the first prompt will either ask for the password or return Alreadyin use if already 20 clients are connected (see First Prompt (see page 6)). After the first prompt, a command
START must be sent. After that, the API sends• a settings message. This settings is also sent whenever a setting on the XL3 is changed• every 500ms a data message until the connection is closed.

Command
START "options"Parameter

Parameter Type

Comment
123'options'

STR

Request the settings and results of 123 screen
123 Spectrum

Same as 123, but adds also the Spectrum

Answer
JSON settings
JSON data every 500ms

www.nti-audio.com

Page 15

XL3 API Manual
Streaming API

Example: 123 values
START 123

Settings:{"error": "NONE","settings": {"123": [{"name": "L`AF", "limit": {"on": false, "red": 100,"amber": 90}},{"name": "L`Aeq","limit": {"on": false, "red": 100,"amber": 90}},{"name": "L`AF", "limit": {"on": false, "red": 100,"amber": 90}},{"name": "L`CPK","limit": {"on": false, "red": 100,"amber": 90}},{"name": "L`AFmax","limit": {"on": false, "red": 100,"amber": 90}}],"device_name": "My XL3","running": true,"timer": {"mode": "CONTINUOUS", "set": "00:00:00"}}}}

Data (every 500ms):{"data": {"timer": "00:02:39","123": [34.1, 43.0, 55.7, 31.6, 61.2]}}

www.nti-audio.com

Page 16

XL3 API Manual
Streaming API

Example: 123 and spectrum values
START 123 Spectrum

Settings:{"error": "NONE","settings": {"123": [{"name": "L`AF", "limit": {"on": false, "red": 100,"amber": 90}},{"name": "L`Aeq","limit": {"on": false, "red": 100,"amber": 90}},{"name": "L`AF", "limit": {"on": false, "red": 100,"amber": 90}},{"name": "L`CPK","limit": {"on": false, "red": 100,"amber": 90}},{"name": "L`AFmax","limit": {"on": false, "red": 100,"amber": 90}}],"device_name": "My XL3","running": true,"timer": {"mode": "CONTINUOUS", "set": "00:00:00"},"spectrum": {"name": "live","octres": "1/3", "bands": 36}}}}

Data (every 500ms):{"data": {"timer": "00:02:39","123": [34.1, 43.0, 55.7, 31.6, 61.2],"spectrum": [34.3, 45.6, 52.8, 49.0, 46.0, 38.2, 35.0, 31.3, 30.0, 33.5,
28.2, 40.9, 40.6, 38.7, 40.1, 39.6, 27.7, 27.3, 19.2, 18.8,
22.5, 18.1, 18.7, 20.3, 16.9, 17.9, 14.5, 19.4, 19.2, 17.4,
16.8, 15.1, 15.0, 12.4, 10.0, 14.2]}}

www.nti-audio.com

Page 17

XL3 API Manual
Streaming API

Message

Parameter
NONE no error

error

NOT_IN_SLM Basic streaming is only supported in the Sound Level

Meter function
Indicator name containing supscript info for formatting.
namesettings

data

For example L`AF´+k1 should be printed like
Typical code in html for printing the name:name.replace(/`/g, '<sub>').replace(/´/g, '</sub>')

running

Measurement is running, true or false

timer /
mode

Setting of the measurement timer
CONTINUOUS , SINGLE , REPEATED_SYNC

timer / set

Duration setup for the timer

timer

Current value of the measurement timer

Python example
from websocket import create_connection# websocket --> install websocket-client (https://github.com/websocket-client/websocket-client)
ConnectKey = "ABCDE-FGHIJ"
XL3Password = b"1234"
url = "wss://connect.nti-audio.com/" + ConnectKey + "/api/live/"xl3 = create_connection(url)passwordPrompt = xl3.recv()xl3.send((XL3Password+b'\n'))xl3.send(b"START 123\n")while True:
print(xl3.recv())

www.nti-audio.com# Settings & results

Page 18

XL3 API Manual
Streaming API

Advanced Streaming API
Introduction
The XL3 can stream SPL results, spectral data, SOH (state of health) and the data of a connected weather
station to a client, typically a server running a Noise Monitoring service. Besides live data, the XL3 also
supports retrieving historical data. So, when a server loses the connection to an XL3, no relevant data is lostand can be requested when the connection is established again.
The Streaming API requires some settings on the XL3, which can not be set via the UI. They are set byloading a configuration file.

Configuring the XL3
Configurations of the XL3 are organized in JSON format. When the XL3 loads a configuration, it first sets allparameters to default and then loads the JSON.
The internal storage of the XL3 contains two helpful files:
File

Comment

Configurations/default.xl3cfg

Default values for all XL3 settings

Configurations/documentation.txt

Available values for all XL3 settings

www.nti-audio.com

Page 19

XL3 API Manual
Streaming API

Typical configuration file
The content of a typical configuration file when using the streaming API:{ "MeasurementID": "SLM", "UUID": "00000000-0000-0000-0000-000000000000" }##CONFIG:{"system_settings": {"connections": {"watchdog": "on"},"measurement": {"save_mode": "automatic"}},"SLM": {"auto_run": "on","report_logging": {"logging": {"utc_for_text_files": "off","file_format": "binary","folder_struct": "noisemonitoring","audio": {"mode": "on"}},"spectra": "eq, max, min"}}}www.nti-audio.com

Page 20

XL3 API Manual
Streaming API

Important Settings for Streaming
Setting

Description
on

The XL3 will automatically restart if there is no internet connection for one
hour. A maximum of two restarts is executed within 12 hours.
An eye symbol in the top bar of the XL3 display represents the activation of
the watchdog. When a network connection is active, the eye symbol toggles
with the network symbol.
watchdog

recommend switching this function on for unattended noise We
monitoring applications.

off (default)
Watchdog is off
automatic
save_mode

Measurement is saved automatically. In this mode, the file push service canpush each completed file.
assisted (default) manually
Not recommended for streaming or unattended noise monitoring.
on

auto_run• the XL3 will automatically start the measurement when the configurationis activated.
• in case of an error (e.g. if the storage is unavailable), the XL3 tries torestart the measurement every 10 seconds.
• the measurement can be stopped manually, for example, to execute a
calibration. During this “local operation”• the measurement is automatically started again if there was no userinteraction for 60 seconds (as long the configurations was not exitedby the operator).
• Configuration sent via the the Streaming API are rejected. See Local
operation (see page 26) for more details.
off (default)

If auto_run was on before, an ongoing measurement will be stopped andsaved when the configuration is received.
file_format

www.nti-audio.com

text_tsv (default)
Tabulator separated text files (default)

Page 21

XL3 API Manual
Streaming API

Setting

Description
binaryRequired for streaming SPLLOG. XL3 can only stream data from binary files.
Binary files contain the same information as text files but can be accessed
faster by machines.
text_tsv + binary

Both file types are generated simultaneously
standard (default)
Measurements are organized in project folders (default)
noisemonitoring
folder_structure

utc_for_text_files

Mandatory for streaming:• Measurements are organized in YEAR/MONTH, allowing machines to findthe correct files quickly.
• Data is stored based on UTC.
• When the free space on the storage gets below 1GByte, the oldest
measurement folder and its content are deleted.
Specifies which time zone is used for• text files• the Broadcast Audio Extension Chunk of wave files.
off (default)
Local timeonUTCwww.nti-audio.com

Page 22

XL3 API Manual
Streaming API

Data Stream Channels
Channels ID
The streaming API is organized through the following channels:
ChannelChannel ID

Description

SYSTEM

0

Commands and errors

SPLLOG1

SLM log data

SPLREP

5

SLM report data

AUDIO

2

Audio data

SOH

3

State of health data

WEATHER

4

Weather data

Live Data

Historical Data

Content ID
Channels need to be opened once by a command. The device then sends responses of the following type:Content-Type

Content ID

Description

Error

1

Error message with error binary error number and ASCII error text

Begin of stream

2

The package contains begin of stream data, usually the data header.

Data

3

Channel-dependent streamed data

End of stream

4Marks the end of a stream

www.nti-audio.com

Page 23

XL3 API Manual
Streaming API

Channel states
Channels follow this flow: Terminate commands with new line “\n”
XL3 Message format
Messages sent by the XL3 follow this format:

 Messages from XL3 are designed to be first split by ; .
Then, split individual packets by |www.nti-audio.com

Page 24

XL3 API Manual
Streaming API

SYSTEM Channel
Command:
SYST:CONF 'Name', Base64ConfigData

Configures the XL3 with the Base64ConfigData.
Parameter

Parameter Type

Comment'Name'QSTR

Name of the file used to store the configuration in
the Configuration folder of the XL3.

Base64ConfigData

STR

Base64 coded configuration files. For example,
Typical configuration file (see page 20) coded as
Base64.

Answer:
1;0;ERROR_NUMBER;ERROR_TEXT

Example:SYST:CONF 'MyConfig',eyAiTWVhc3VyZW1lbnRJRCI6ICJTTE0iLCAiVVVJRCI6ICIwMDAwMDAwMC0wMDAwL
TAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiIH0NCiMjQ09ORklHOg0Kew0KICAgICJzeXN0ZW1fc2V0dGluZ3MiOiB
7DQogICAgICAgICJjb25uZWN0aW9ucyI6IHsNCiAgICAgICAgICAgICJ3YXRjaGRvZyI6ICJvbiINCiAgICAgICAgfSwNCiAgICAgICAgIm1lYXN1cmVtZW50Ijogew0KICAgICAgICAgICAgInNhdmVfbW9kZSI6ICJhdXRvbWF
0aWMiDQogICAgICAgIH0NCiAgICB9LA0KICAgICJTTE0iOiB7DQogICAgICAgICJhdXRvX3J1biI6ICJvbiIsD
QogICAgICAgICJyZXBvcnRfbG9nZ2luZyI6IHsNCiAgICAgICAgICAgICJsb2dnaW5nIjogew0KICAgICAgICA
gICAgICAgICJmaWxlX2Zvcm1hdCI6ICJiaW5hcnkiLA0KICAgICAgICAgICAgICAgICJmb2xkZXJfc3RydWN0I
jogIm5vaXNlbW9uaXRvcmluZyIsDQogICAgICAgICAgICAgICAgImF1ZGlvIjogew0KICAgICAgICAgICAgICA
gICAgICAibW9kZSI6ICJvbiINCiAgICAgICAgICAgICAgICB9DQogICAgICAgICAgICB9LA0KICAgICAgICAgICAgInNwZWN0cmEiOiAiZXEsIG1heCwgbWluIg0KICAgICAgICB9DQogICAgfQ0KfQ0K
1;0;0;OK

Steps executed by this command:• Decodes the Base64ConfigData and stores it in the XL3 Configurations folder using the name Name .xl
3cfg.
• Checks if applying configuration requires restarting an ongoing measurement. If yes, stop themeasurement.
• Load the configuration.
• Restart the measurement if it was stopped before (or if auto_run is set to on in the configuration).
is good practice to send this command whenever the Streaming API WebSocket to the device is Itopened.

www.nti-audio.com

Page 25

XL3 API Manual
Streaming API

Python example:
import base64
from websocket import create_connection# websocket --> install websocket-client (https://github.com/websocket-client/websocket-client)def getConfigFileAsBase64(file_name):"""Reads a file and returns its content as base64 encoded string"""with open(file_name, 'rb') as file:
file_content = file.read()base64_content_s = base64.b64encode(file_content)
return base64_content_s
ConnectKey = "ABCDE-FGHIJ"
XL3Password = b"1234"
url = "wss://connect.nti-audio.com/" + ConnectKey + "/api/stream1/"
xl3 = create_connection(url)passwordPrompt = xl3.recv()xl3.send((XL3Password+b'\n'))print(xl3.recv())# Identification Message

ConfigBase64 = getConfigFileAsBase64("MyConfigFile.xl3cfg")
q = b"SYST:CONF 'ApiDemo'," + ConfigBase64 + b"\n"xl3.send(q)print(xl3.recv())

Local operation when a configuration is active
When auto_run is configured, and the operator locally stops the measurement (for example, to execute a
calibration), sending SYST:CONF will result in an error 1050 (Loading configuration failed: Local operation
active). The XL3 will accept the command again• once the measurement was restarted, either manually by the operator or automatically through auto_run• the operator exited the configuration (which will disable auto_run)

www.nti-audio.com

Page 26

XL3 API Manual
Streaming API

SPLLOG Channel
Command:
SPLLOG START_TIME_REQ, "Indicators List" [, MAX_HISTORY_LINES]

Request results from the SLM logging data starting from the START_TIME_REQ time.
Parameter

Parameter Type

Comment

START_TIME_REQ

INTUNIX timestamp * 1000 (ms)https://www.epochconverter.com/'Indicators List'

QSTR

List of values required as a quoted stringe.g. “LAEQ LAFMAX“

INT

Optional Parameter: Specifies the maximum numberof lines of history data that will be streamed before
the stream will stop, valid range is 10 to 1000, or -1 if
as many data lines as possible should be streamed(if parameter not given: default is 1000).
Note: If value is out of valid range the value is
automatically and silently adjusted.
Note: This limitation takes only effect for history dataand not for live data.

MAX_HISTORY_LINES

Answer:2;1;START_TIME_CONF;INTERVAL;NUMBER_OF_INDICATORS;INDICATOR_NAME|INDICATOR_NAME| ...
3;1;TIMESTAMP;RESULT|RESULT ...

A gap in data:
The XL3 sends data in fixed INTERVAL s starting from START_TIME_CONF . The TIMESTAMP is always one
INTERVAL bigger than the TIMESTAMP sent before.

If there is a gap in the data (e.g. because the measurement was stopped and restarted), the channel willclose with an “End of stream” message. When this happens, send the command again with the last received
TIMESTAMP as START_TIME_REQ . The XL3 will then start delivering data after the end of the gap.
Example:SPLLOG 1690196106000, "LAEQ LAFMAX"\n2;1;1690196106000;1000;2;LAEQ|LAFMAX
3;1;1690196107000;45.0|51.4
3;1;1690196108000;34.8|38.3...

www.nti-audio.com

Page 27

XL3 API Manual
Streaming API

3;1;16901961321000;34.8|38.3
4;1
SPLLOG 16901961321000, "LAEQ LAFMAX"\n2;1;1690898194000;1000;2;LAEQ|LAFMAX
3;1;1690898195000;65.4|67.8
3;1;1690898196000;57.8|59.2

Example with optional parameter:
spllog 1710928800000, "laeq lafmax", 20\n2;1;1710928800000;1000;2;LAEQ|LAFMAX
3;1;1710928801000;34.6|35.0
3;1;1710928802000;34.7|35.3
3;1;1710928803000;35.1|35.9...
3;1;1710928820000;34.6|36.5
4;1

Examples of failed requests:
A request with an unknown indicator “ABC”:
SPLLOG 1690288491000, "ABC"\n1;1;40;PARSER ERROR 40

Requesting data from “now”, but no measurement is running:
SPLLOG 1690288809000, "LAEQ LAFMAX"\n1;1;10000;NO DATA FOUND ERROR 1

Indicator List:
Group

Available indicators
LxyMAX LxyMIN LxIMAX LxIMIN
LxEQ LxIEQ LxE LxPKMAX LAFT3 LAFT5Broadband

LAEQ_G1 LAEQ_G2 LAEQ_G3 LAEQ_G4
LCEQ_G1 LCEQ_G2 LCEQ_G3 LCEQ_G4
LN1 ... LN7

www.nti-audio.com

Page 28

XL3 API Manual
Streaming API

Group

Available indicators
1/1 octave resolution:
OCT_xEQ OCT_xyMIN OCT_xyMAX

SpectrumAll bands

OCT_xyN1 ... OCT_xyN7

1/3 octave resolution:
3OCT_xEQ 3OCT_xyMIN 3OCT_xyMAX
3OCT_xyN1 ... 3OCT_xyN7

1/1 octave resolution, # = 1 … 12 (8Hz … 16kHz):
OCT#_xEQ OCT#_xyMIN OCT#_xyMAX

Spectrum
Individual bands

OCT#_xyN1 ... OCT#_xyN7

1/3 octave resolution, # = 1 … 36 (6.3Hz … 20kHz):
3OCT#_xEQ 3OCT#_xyMIN 3OCT#_xyMAX
3OCT#_xyN1 ... 3OCT#_xyN7

x = [A|C|Z]
y = [F|S]
278 results can be streamed. A spectrum counts as 36 for 1/3 octave resolution and 12 for 1/1 octave
resolution.

www.nti-audio.com

Page 29

XL3 API Manual
Streaming API

With the default settings,• spectral data is available in 1/3 octave resolution, Z frequency weighting and F time weighting.
• Gliding LEQs (e.g. LAEQ_G1) have 5sec, 10min, 15min and 60min averaging time.
• Level Statistics (e.g. LN1) are set to 1.0%, 5.0%, 10.0%, 50.0%, 90.0%, 95.0% and 99.0%.
Broadband statistics are based on LAF, spectral statistics on the frequency and time weighting of thespectrum (“fwtw”)
To change these settings, adapt and use this configuration:{ "MeasurementID": "SLM", "UUID": "00000000-0000-0000-0000-000000000000" }##CONFIG:{"SLM": {"auto_run": "on","report_logging": {"logging": {"utc_for_text_files": "off","file_format": "binary","folder_struct": "noisemonitoring","audio": {"mode": "on"}},"spectra": "eq, max, min"},"spectrum": {"octres": "1/3","hold_time": "3 sec","fwtw": "ZF"},
"gliding_eq": {"average_time": {"1": "5 sec","2": "10 min","3": "15 min","4": "60 min"}},"percentile": {"1": 1.0,"2": 5.0,"3": 10.0,"4": 50.0,"5": 90.0,"6": 95.0,"7": 99.0,"source": "AF"}}}www.nti-audio.com

Page 30

XL3 API Manual
Streaming API

SPLREP Channel
Command:
SPLREP START_TIME_REQ, "Indicators List" [, MAX_HISTORY_LINES]

Request results from the report data starting from the START_TIME_REQ time.

 The XL3 records aggregated report data when the timer mode is set to “Repeated”.
{ "MeasurementID": "SLM", "UUID": "00000000-0000-0000-0000-000000000000" }##CONFIG:{"SLM": {"timer": {"mode": "Repeated","set": {"repeated_ms": 300000}}}}

Parameter

Parameter Type

Comment

START_TIME_REQ

INTUNIX timestamp * 1000 (ms)https://www.epochconverter.com/"Indicators List"

QSTR

List of values required as a quoted stringe.g. “LAEQ LAFMAX“
Indicator list (see page 28)

INT

Optional Parameter: Specifies the maximum numberof lines of history data that will be streamed before
the stream will stop, valid range is 10 to 1000, or -1 if
as many data lines as possible should be streamed(if parameter not given: default is 1000).
Note: If value is out of valid range the value is
automatically and silently adjusted.
Note: This limitation takes only effect for history dataand not for live data.

MAX_HISTORY_LINES

Answer:2;5;START_TIME_CONF;0;NUMBER_OF_INDICATORS;INDICATOR_NAME|INDICATOR_NAME| ...

www.nti-audio.com

Page 31

XL3 API Manual
Streaming API

3;5;TIMESTAMP;DURATION;RESULT|RESULT ...

 When a measurement is started and/or stopped, the DURATION of the first and the last data
message may differ from the set repeated_ms duration.

www.nti-audio.com

Page 32

XL3 API Manual
Streaming API

A gap in data:
The XL3 sends data starting from START_TIME_CONF . After the first data line, the TIMESTAMP is always
one DURATION bigger than the TIMESTAMP sent before.
If there is a gap in the data (e.g. because the measurement was stopped and restarted), the channel willclose with an “End of stream” message. When this happens, send the command again with the last received
TIMESTAMP + DURATION as START_TIME_REQ . The XL3 will then start delivering data after the end of thegap.

 Continuing after a gap is different between SPLLOG and SPLREP
Example:SPLREP 1695214350000, "LAEQ LAFMAX"\n2;5;1695214372000;0;2;LAEQ|LAFMAX
3;5;1695214372000:8000;45.0|51.4
3;5;1695214380000;15000;34.8|38.3
3;5;1695214395000;15000;51.1|69.8...
3;5;1695214770000;15000;48.8|60.8
3;5;1695214785000;11000;34.8|38.3
4;5
SPLREP 1695214796000, "LAEQ LAFMAX"\n2;5;1695214800000;0;2;LAEQ|LAFMAX
3;5;1695214800000;15000;65.4|67.8
3;5;1695214815000;15000;57.8|59.2

www.nti-audio.com

Page 33

XL3 API Manual
Streaming API

AUDIO Channel
Command:
AUDIO START_TIME_REQ, DURATION

Request audio data from START_TIME_REQ with the length DURATION (in seconds)
Answer:2;2;BASE64_WAVE_FILE_HEADER
3;2;BASE64_WAVE_FILE_DATA...
3;2;BASE64_WAVE_FILE_DATA
4;2

To get an actual wave file, decode the BASE64_WAVE_FILE_HEADER and the BASE64_WAVE_FILE_DATA
and store the result in a file with the ending ".wav".
The wave file includes a Broadcast Audio Extension Chunk, which describes the content of the wave file. See
https://tech.ebu.ch/docs/tech/tech3285.pdf for a full specification. The chunk also includes date and time
information, which is either in local time or UTC, dependent on the "utc_for_text_files” setting.
Example:Audio 1690547362000, 3\n2;2;UklGRviRAABXQVZFZm10IBQAAAARAAEAwF0AAIYvAAAAAQQAAgD5AWZhY3QEAAA...
3;2;7Oc2AKSMQpGZGCOq0g4CCIqSWcFSE8mLAggouEMRiLAsR5iJQso1MMHKUaKdMaO...
3;2;mAohALqSrFCZ6QEIi5mZ8w0ImZwDyI5AwQExkJ2wqZ0ZA9uaQZkwFwgqgZgh2Dj...
...
3;2;B94nAEgYggBDUSE0BBkiQQFiIRMhMiMMJyIIJDGBJWCEOJoCs0lZkiUJQCGUQkk...
4;2

www.nti-audio.com

Page 34

XL3 API Manual
Streaming API

Getting Audio - Programming Example (Python 3.8):
from websocket import create_connection
import time
import base64
ConnectKey = "ABCDE-FGHIJ"
url = "wss://connect.nti-audio.com/api/" + ConnectKey + "/stream2/"
ws = create_connection(url)passwordPrompt = ws.recv()
ws.send(b'1234\n')identificationMessage = ws.recv()
print(identificationMessage)
now = (int(time.time()) - 60) * 1000
q = b'Audio %d, 3\n' % now
ws.send(q)print(q)response = ws.recv().decode("utf-8").strip()
print(response)
if response[0] == "2": # Begin of stream
waveFile = base64.b64decode(response[4:])while True:
response = ws.recv().decode("utf-8").strip()
if response[0] == "3":# DatawaveFile += base64.b64decode(response[4:])if response[0] == "4":# End of stream
with open("xl3-demo.wav", "wb") as file:
file.write(waveFile)break
ws.close()

www.nti-audio.com

Page 35

XL3 API Manual
Streaming API

SOH Channel
Command:
SOH

Request streaming of SOH data.
Answer:2;3;START_TIME_CONF;INTERVAL;NUMBER_OF_RESULTS;RESULT_LIST;RESULT_UNITS

Parameter

ExampleUnit

Comment

INTERVAL

60000

ms

Always 60000

NUMBER_OF_RESULTS

13

LocalTime2023-07-24
12:55:00

TimeZone

Europe/Berlin

BatterySOC

100

RunStatus

RUNNING

WeatherStations

0

VDcIn

9.67

V

Voltage on the power supply connector

IPhantom

0.011

A

Current consumption of the connected
microphone.

FreeStorage

283397.625

MB

GpsLocation

47.176090
9.512550

DegreeLatitude Longitude(requires optional external GPS receiver)

Temperature

36.0

°C

Temperature inside of the XL3

AirPressure

965.4

hPa

www.nti-audio.com

Always 13%

State of charge of the battery pack (0 ..
100)
Empty if there is no battery inserted

Number of detected weather stations (0..3)

Page 36

XL3 API Manual
Streaming API

Parameter

ExampleUnit

Comment

PowerSource

DcIn

External power source connected to XL3:
None , USB or DcIn

ClockSource

NTP

Source of the internal clock
Internal , NTP , GPS , PPS When fields of the result cannot be determined, they will be left blank.

Example:SOH\n2;3;1698139974358;60000;13;LocalTime|TimeZone|BatterySOC|RunStatus|WeatherStations|
VDcIn|IPhantom|FreeStorage|GpsLocation|Temperature|AirPressure|PowerSource|
ClockSource;-|-|%|-|-|V|A|MB|deg|degC|hPa|-|3;3;1698139974398;2023-10-18 04:47:00|Europe/Berlin||Running|2|9.15|0.004|1920.090||
36.0|965.4|DcIn|NTP

www.nti-audio.com

Page 37

XL3 API Manual
Streaming API

WEATHER Channel
Command:
WEATHER START_TIME_REQ [, MAX_HISTORY_LINES]

Request results from the Weather logging data starting from the START_TIME_REQ time.
Parameter

Parameter Type

Comment

START_TIME_REQ

INTUNIX timestamp * 1000 (ms)https://www.epochconverter.com/

INT

Optional Parameter: Specifies the maximum numberof lines of history data that will be streamed before
the stream will stop, valid range is 10 to 1000, or -1 if
as many data lines as possible should be streamed(if parameter not given: default is 1000).
Note: If value is out of valid range the value is
automatically and silently adjusted.
Note: This limitation takes only effect for history dataand not for live data.

MAX_HISTORY_LINES

Answer:2;4;START_TIME_CONF;INTERVAL;NUMBER_OF_WEATHER_STATIONS;...
3;4;TIMESTAMP;RESULT|RESULT ...

If there is a gap in the recorded data, the behaviour is similar to that described for the SPLLOG channel (seepage 27).
Example:WEATHER 1701429720000
2;4;1701426240000;60000;1;Vaisala;USB;R3750165;6;S1|S1|S1|S1|S1|S1;Speed_Min|
Speed_Avg|Speed_Max|Dir_Min|Dir_Avg|Dir_Max;m/s|m/s|m/s|deg|deg|deg
3;4;1701426300000;0.00|0.00|0.10|90.00|86.00|180.00
3;4;1701426360000;0.00|0.00|0.10|90.00|91.00|330.00

When two weather stations are connected:
WEATHER 1701429720000
2;4;1701426240000;60000;2;Vaisala|LCJ Capteur;USB|SDI-12.A1;R3750165|00000;12;S1|S1|
S1|S1|S1|S1|S2|S2|S2|S2|S2|S2;Speed_Min|Speed_Avg|Speed_Max|Dir_Min|Dir_Avg|Dir_Max|
Speed_Min|Speed_Avg|Speed_Max|Dir_Min|Dir_Avg|Dir_Max;m/s|m/s|m/s|deg|deg|deg|m/s|m/s|
m/s|deg|deg|deg'

www.nti-audio.com

Page 38

XL3 API Manual
Streaming API

3;4;1701426300000;0.00|0.00|0.10|90.00|86.00|180.00|0.20|0.40|4.50|188.00|155.00|
133.003;4;1701426360000;0.00|0.00|0.10|90.00|91.00|330.00|0.20|0.40|4.50|188.00|155.00|
133.00Using multiple channels… on the same WebSocket
Multiple channels can be used on the same WebSocket:
Example:NTi Audio XL3 Streaming API Text, A3A-00100-D0, 1.28
SYST:CONF 'MyConfig',eyAgIk1lYXN1cmVtZW50SUQiOiAiU0xNIiwgIlVVSUQiOiAiMDAwMDAwMDAtMDAwM
C0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiB9DQojI0NPTkZJRzoNCnsNCiAgICAiU0xNIjogew0KCQkiYXV0b19
ydW4iOiAib24iLA0KICAgICAgICAic3BlY3RydW0iOiB7DQogICAgICAgICAgICAib2N0cmVzIjogIjEvMyIsD
QogICAgICAgICAgICAiZnd0dyI6ICJaRiINCiAgICAgICAgfSwNCiAgICAgICAgInJlcG9ydF9sb2dnaW5nIjo
gew0KICAgICAgICAgICAgImxvZ2dpbmciOiB7DQogICAgICAgICAgICAgICAgImZpbGVfZm9ybWF0IjogImJpb
mFyeSIsDQogICAgICAgICAgICAgICAgImZvbGRlcl9zdHJ1Y3QiOiAibm9pc2Vtb25pdG9yaW5nIiwNCiAgICA
gICAgICAgICAgICAiYXVkaW8iOiB7DQogICAgICAgICAgICAgICAgICAgICJtb2RlIjogIm9uIg0KICAgICAgICAgICAgICAgIH0NCiAgICAgICAgICAgIH0sDQogICAgICAgICAgICAic3BlY3RyYSI6ICJlcSwgbWF4LCBtaW4iDQogICAgICAgIH0NCiAgICB9DQp9DQo=
SPLLOG 1690196106000, "LAEQ LAFMAX 3oct_zeq"
SOH
WEATHER 1690196106000
1;0;0;OK2;1;1690196106000;1000;38;LAEQ|LAFMAX
2;3;1690196107036;60000;9;LocalTime|TimeZone|BatterySOC|RunStatus|WeatherStations|
VDcIn|IPhantom|FreeStorage|GpsLocation;-|-|%|-|-|V|A|MB|deg
3;3;1690196100244;2023-07-24 12:55:00|Europe/Berlin|100.0|Running|1|9.67|0.011|
483397.625|
2;4;1690196107000;60000;1;Vaisala;USB;R3750165;6;S1|S1|S1|S1|S1|S1;Speed_Min|
Speed_Avg|Speed_Max|Dir_Min|Dir_Avg|Dir_Max;m/s|m/s|m/s|deg|deg|deg
3;4;1690195107000;0.00|0.10|0.20|90.00|186.00|270.00
3;1;1690196107000;42.1|48.3
3;1;1690196108000;38.0|42.4
3;1;1690196109000;33.2|36.7
3;1;1690196110000;33.4|34.2
3;1;1690196111000;38.7|44.1
3;1;1690196112000;33.5|38.9
3;1;1690196113000;32.8|34.6

www.nti-audio.com

Page 39

XL3 API Manual
Streaming API… on different WebSockets
The Streaming API offers two TCP ports / two WebSockets, which can be used simultaneously with therestriction that only one channel may be opened simultaneously.
Example:• WebSocket1 could be used to stream SOH, SPLLOG and Weather data.
• WebSocket 2 could be used for querying Audio.
Opening a SOH stream on WebSocket 2 would result in the following error message:
1;3;9001;Attempt to use an already opened channel: Stream SOH Channel\n'

www.nti-audio.com

Page 40

XL3 API ManualControl API

Control API
Introduction
The XL3 can be controlled and queried remotely using the Control API from external client software with acommand set. The command set allows you to set up the device, Start/Stop measurements, and retrieve
measurement results. This interface is typically used for measurement applications like acoustic test stands
or end-of-line testing.

Command Structure
Remote commands are sent in ASCII format to the XL3. The line feed character (LF, 0x0A) is the message
terminator for XL3 commands. So, every command transmission from your PC to your XL3 or vice versa has
to be terminated with a line feed LF. The measurement commands are divided into subsystems (i.e. logicalgroups).
Subsystem

Function*

Device status common commands

INITiate

Status control for a measurement

MEASurement

Measurement result query commands

INPut

Sensor settings command

CALIbrate

Sensor calibration commands

ASD

Microphone Automatic Sensor Detection commands

SYSTemSystem status commands

Command Format
The XL3 accepts either total keywords (long form) of commands or their abbreviations (short form). In thecommand list, the CAPITAL letters indicate the abbreviation. However, the XL3 accepts lowercase and
UPPERCASE letters as input, i.e. commands and parameters are not case-sensitive.
The command description contains special symbols (see page 82) and parameter types (see page 82).
strings in commands may not contain blanks or other characters, which may be Unquoted
interpreted as control characters or separators. Strings embedded in quotation marks may include
all characters except the message termination character (LF).

www.nti-audio.com

Page 41

XL3 API ManualControl API

Command Responses
Commands that query the XL3 for values have a “?“ at the end of the command. Query commands return a
response (Answer). Commands that set values in the XL3 have no “?“. Set commands do not return a
response.
responds to each command with LF. The XL3 sends the command response only after the XL3
command is executed by the XL3. In other words, until the LF is returned, no other command canbe processed by the XL3.

This is especially helpful for synchronizing commands that need a little time. e.g. for the INIT START
command, the answer LF is sent when the measurement starts (after the settling time reaches 0). This
makes it easy to synchronize further actions.
When there is no response, something went wrong. Please check the error queue (see page 42).

Error Queue
Errors are stored in the error queue and can be queried with the SYSTem:ERRor? (see page 73) command. If anerror occurs during the execution of a command or a query, a corresponding error is pushed into the error
queue. A semicolon is returned instead of the expected answer if the command is a query.

Multiple Commands
Multiple commands separated by semicolons ";" are supported, e.g. meas:init;:syst:err?
Notice that a command tree reset character (“:” as shown in the example above) is required for a subsequentcommand if the last node is not re-used. The commands are processed one after the other. The following
command is only executed when the last one is completed. The response of multiple commands isseparated by “;” and one LF at the line end. If there is a semicolon without a preceding value, it is an error.
Check the error queue.

Timeouts
When using the API, the following timeouts should be used (or longer ones):
For what?

ExampleTimeout (minimum)

General

MEAS:INIT

3 sec

Starting a measurement

INIT START

13 secSwitching measurement functions

MEAS:FUNC SLM

5.5 sec

www.nti-audio.com

Page 42

XL3 API ManualControl API

Command-List
Device Status*IDN?
Shortcut

Identification: Reads the unique identification of the XL3.

Availability

always<Manufacturer>,<Unit>,<Serial Number>,<FW Version>

Answer

STR, STR, STR, STR
Common command according to IEEE488.2-1992 10.14.3

Example*IDN?
NTi Audio XL3 Control API, A3A-00129-B1, 0.90.4760*CLS
Shortcut

Executes a status reset: Clears the error queue and the output buffer.

Availability

alwaysExample*CLS
LF

www.nti-audio.com

Page 43

XL3 API ManualControl API*RST

Shortcut

Executes a device reset and should be the first command when starting a remotesession to ensure that all XL3 settings make sense for remote measuring.

Availability

alwaysExample*RST
LF

Details

www.nti-audio.com

When using the Control API, execute this command first to avoid unwanted side
effects.
This command:• stops any running measurement• ends Measurement Series• exits any configuration• selects the Sound Level Meter function and sets the following:• Logging interval: off• Save mode: off• Spectrum• 1/3 Octave resolution• LZF• Gliding & Level Statistics to default values• Timer mode: Continuous

Page 44

XL3 API ManualControl API

INITiate Subsystem
INITiate
ShortcutStarts or stops a measurement

Availability

Sound Level Meter[ START | STOP ]Parameter
CHARDAT
ExampleDetails

INIT START

Time-dependent parameters like LAeq, LAFmax, etc., are undefined until START has
been initiated. The start procedure may take a few seconds. When a measurement is
stopped with STOP, the calculation of time-dependent parameters is stopped, and theresult stays constant.
If measurement series is enabled, the measurement can not be started or stopped. In
this case, error 1048 is pushed to the error queue.
START, the answer LF is sent when the start procedure has finished.
 For
For STOP, any save dialog is suppressed.

INITiate:STATe?
Shortcut

Queries the run status of a measurement

Availability

always[ STOPPED | FROZEN | SETTLING | RUNNING | PAUSED | UNDEFINED ]Answer
CHARDAT

Examplewww.nti-audio.com

INIT:STATE?
RUNNING

Page 45

XL3 API ManualControl API

MEASure Subsystem
MEASure:INITiate
Shortcut

Triggers a measurement

Availability

always
MEAS:INIT

ExampleAll measurement results of the MEASure subsystem are stored synchronously by thiscommand. Before the first MEAS:INIT has been sent, all measurement values are
undefined.
A typical workflow is
INIT START
MEAS:INIT
MEAS:SLM:123? <para1>, <para2>
MEAS:INIT
MEAS:SLM:123? <para1>, <para2>...

Details

MEASure:TIMer?
Shortcut

Queries the actual measurement timer value.

Availability

Sound Level Meter<timer> sec

Answerfloat UNIT
0.1 seconds resolution (1 decimal)

ExampleDetails

www.nti-audio.com

MEAS:INIT
MEAS:TIMER?
3765.0 sec

This represents the time since initiating START

Page 46

XL3 API ManualControl API

MEASure:TIMer:MODE
ShortcutDefines the timer mode

Availability

Run state = STOPPED[ CONTinuous | SINGle | REPEated ]Parameter
CHARDAT
Example

MEAS:TIM:MODE CONT

Details

MEASure:TIMer:MODE?
Shortcut

Queries the timer mode

Availability

always[ CONTINUOUS | SINGLE | REPEATED ]Answer
CHARDAT

Example

MEAS:TIM:MODE?
CONTINUOUS

MEASure:TIMer:SET:SINGle
Shortcut

Sets the time value for the single mode

Availability

Run state = STOPPED<timer value>

Parameter

www.nti-audio.com

NUM_L
Unsigned integer value in milliseconds

Page 47

XL3 API ManualControl API

ExampleDetails

MEAS:TIM:SET:SING 30000

If the given value is outside of the valid range, the set value is corrected to the
maximum or minimum, respectively.
An error is returned if the given value is outside the range for a 32-bit unsigned integer.

MEASure:TIMer:SET:SINGle?
Shortcut

Queries the timer value for the single mode. The value is returned in milliseconds.

Availability

always<timer value>

Answer
NUM_L

Example

MEAS:TIM:SET:SING?
30000

MEASure:TIMer:SET:REPEated
Shortcut

Sets the time value for the repeated mode

Availability

Run state = STOPPED<timer value>

Parameter

ExampleDetails

www.nti-audio.com

NUM_L
Unsigned integer value in milliseconds
MEAS:TIM:SET:REPE 180000

If the given value is outside of the valid range, the set value is corrected to the
maximum or minimum, respectively.
An error is returned if the given value is outside the range for a 32-bit unsigned integer.

Page 48

XL3 API ManualControl API

MEASure:TIMer:SET:REPEated?
Shortcut

Queries the timer value for the repeated mode. The value is returned in milliseconds.

Availability

always<timer value>

Answer
NUM_L

Example

MEAS:TIM:SET:REPE?
180000

MEASure:FUNCtion
ShortcutDefines the active measurement function

Availability

Run state = STOPPED[ SLM | RT | SI ]Parameter
CHARDAT
Example

MEAS:FUNC SLM

Details

Switching between measurement functions may take 1-2 seconds.
Leaves a possibly active configuration.

Restrictions

The SI parameter is only available if the Sound Insulation Option is installed

MEASure:FUNCtion?
Shortcut

Queries the active measurement function

Availability

always[ SLM | RT | SI ]Answer
CHARDAT

www.nti-audio.com

Page 49

XL3 API ManualControl API

MEAS:FUNC?
SLM

ExampleMEASure:DECImals

ShortcutSelects the number of decimals of SLM wideband and spectrum results. This setting is
not persistent and is reset to the default value LCD on device startup and kept until thedevice is reboot. The extended setting adds two additional decimals in the result.

Availability

always[LCD|EXTended]

Parameter
CHARDAT
Example

MEAS:DECI EXTMEASure:DECImals?
ShortcutGets the decimals mode

Availability

alwaysExamplewww.nti-audio.com

MEAS:DECI?
EXTENDED

Page 50

XL3 API ManualControl API

MEASure: SLM Subsystem
MEASure:SLM:123?
Shortcut

Queries a broadband measurement result of the Sound Level Meter.

Availability

Sound Level Meter[ LxS | LxSMAX | LxSMIN | LxF | LxFMAX | LxFMIN | LxEQ | Prev_LxEQ | LxPK | LxPKMAX|
LyEQ_gt | LyEQ_gtMAX | LAFT3 | LAFT3EQ | LAFT5 | LAFT5EQ | LAFT5EQ-LAEQ |LCEQ-LAEQ | k1 | k2 ]Parameter

CHARDATx = [A|C|Z], y = [A|C]t = [5sec|10min|15min|60min]
One of the four settings specified on the /Sound Level Meter/Gliding Leq Levels pageof the XL3
e.g. LAEQ_g5sec for LAEQ_g5" or LCEQ_g15minMAX or LCEQ_g15'max[ LxI | LxIEQ | LxIMAX | LxIMIN | Ln% | LAIEQ-LAEQ ]Parameter(Additional withinstalled
Extended
Acoustic Pack)

Answer

CHARDATx = [A|C|Z]n = [1|5|10|50|90|95|99] One of the seven statistic values specified on the /Sound Level
Meter/Level Statistics page of the XL3, e.g. L90.0% (if the decimal place is zero, you
can also use L90%)<Level> dB, [OK|UNDEF|LOW|OVLD]
float UNIT CHARDAT

Examplewww.nti-audio.com

INIT START
MEAS:INIT
MEAS:SLM:123? LASMAX
53.8 dB, OK

Page 51

XL3 API ManualControl API

Returns a broadband result parameter stored by the last MEAS:INIT command. If anerror occurs, e.g. the parameter is unknown, a ";" is returned.

Details

Statistic values:• For custom settings, use the custom values to reade.g. MEAS:SLM:123? L33.3%• Remotely changing/reading the settings is not implemented.
• Be aware of the decimal separator. Use the Decimal Separator Configuration fromthe /System Settings/General page.
parameter keywords are listed in their full keyword notation, even if some
 Alllowercase letters are used to describe special cases. No parameter
keywords have abbreviations.

Call withmultipleparameters

ExampleDetails

This command accepts up to 10 parameters. Each parameter has to be separated by acomma.

INIT START
MEAS:INIT
MEAS:SLM:123? LASMAX, LAFMAX, LZSMAX, LZFMAX
52.1 dB, OK;54.8 dB, OK;6dB, OK;65.3 dB, OK

Because the line feed character (LF) is reserved as the message termination
character, the responses for each parameter are separated by semicolons.
If the query for a specific parameter generates an error, an empty field is returned, andthe corresponding errors are pushed into the error queue. E.g. if L55% is not available:
MEAS:SLM:123? LASMAX, L55%, LAFMAX, L5%
52.1 dB, OK;;54.8 dB, OK;

www.nti-audio.com

Page 52

XL3 API ManualControl API

MEASure:SLM:123:DT?
Shortcut

Queries a broadband dt measurement result of the Sound Level Meter.

Availability

Sound Level Meter[ LxSMAX | LxSMIN | LxFMAX | LxFMIN | LxEQ | LxPKMAX ]Parameter

CHARDATx = [A|C|Z]

Parameter(Additional withinstalled
Extended
Acoustic Pack)[ LxIMAX | LxIMIN | LxE ]CHARDATx = [A|C|Z]<Level> dB, [OK|UNDEF|LOW|OVLD]

Answerfloat UNIT CHARDAT

ExampleINIT START
MEAS:INIT
MEAS:SLM:123:dt? LASMAX
53.8 dB, OK

Queries a broadband result parameter of the Sound Level Meter stored with the last
MEAS:INIT command. dt measurements are cleared after each MEAS:INIT, so thisfunction returns the e.g. LEQ between two MEAS:INIT commands. The values have thesame meaning as the dt values found in XL3 log files.
If the parameter is unknown, a ";" is returned.
Details
parameter keywords are listed in their full keyword notation, even if some
 Alllowercase letters are used to describe special cases. Parameter keywords
don’t have abbreviations.

Call withmultipleparameters

www.nti-audio.com

This command accepts up to 10 parameters. Each parameter has to be separated by acomma.

Page 53

XL3 API ManualControl API

ExampleINIT START
MEAS:INIT
MEAS:SLM:123:dt? LASMAX, LAFMAX, LZSMAX, LZFMAX
52.1 dB, OK;54.8 dB, OK;6dB, OK;65.3 dB, OK

Because the line feed character (LF) is reserved as the message termination
character, the responses for each parameter are separated by semicolons.
If the query for a specific parameter generates an error, an empty field is returnede.g. for the command
Details

MEAS:SLM:123:dt? LASMAX, LAIMAX, LAFMAX, LCIMAX

if the Extended Acoustic Pack Option is not installed, the following string is returned:
52.1 dB, OK;;63.7 dB, OK;

and the corresponding errors are pushed into the error queue.

www.nti-audio.com

Page 54

XL3 API ManualControl API

MEASure:SLM:SPECtrum?
Alternative command keywords for XL2 compatibility: MEASure:SLM:RTA?
Shortcut

Queries the spectral results of the Sound Level Meter.

Availability

Sound Level Meter[ LIVE | MAX | MIN | EQ | CAPT | HOLD3 ]Parameter
CHARDAT[ E | n% ]Parameter(Additional withinstalled
Extended
Acoustic Pack)

CHARDATn = [1|5|10|50|90|95|99] One of the seven statistic values specified on the /Sound Level
Meter/Level Statistics page of the XL3, e.g. 10.0% (if the decimal place is zero, you canalso use 10%)
{Leveln,} dB|dBu|dBV|V, [OK|UNDEF|OVLD]
floats UNIT CHARDAT

Answer
1/1 Oct: n = 12, fstart = 8 Hz
1/3 Oct: n = 36, fstart = 6.3 Hz
Levels sorted from lowest to highest frequency

ExampleDetails

www.nti-audio.com

INIT START
MEAS:INIT
MEAS:SLM:SPEC? EQ
46.3,50.7,34.5,45.4,42.2,37.2,39.0,39.8,32.1,28.5,29.8,31.0 dB, LOW

Queries the spectral results of the Sound Level Meter stored by the last MEAS:INIT
command. If the parameter is unknown, a ";" is returned.
The unit (dB, dBu, dBV, V) is adopted by the setting of the user interface.

Page 55

XL3 API ManualControl API

MEASure:SLM:SPECtrum:DT?
Alternative command keywords for XL2 compatibility: MEASure:SLM:RTA:DT?
Shortcut

Queries the dt spectral results of the Sound Level Meter.

Availability

Sound Level Meter[ EQ ]

Parameter
CHARDAT
Parameter(Additional withinstalled
Extended
Acoustic Pack)[E]

CHARDAT{Leveln,} dB|dBu|dBV|V, [OK|UNDEF|OVLD]
floats UNIT CHARDAT

Answer
1/1 Oct: n = 12, fstart = 8 Hz
1/3 Oct: n = 36, fstart = 6.3 Hz
Levels sorted from lowest to highest frequency

ExampleDetails

www.nti-audio.com

INIT START
MEAS:INIT
MEAS:SLM:SPEC:DT? EQ
46.3,50.7,34.5,45.4,42.2,37.2,39.0,39.8,32.1,28.5,29.8,31.0 dB,
LOW

Queries the spectral results parameter of the Sound Level Meter that has been storedby the last MEAS:INIT command. dt measurements are cleared after each
MEAS:INIT, so this function returns the LEQ of LE between two MEAS:INIT
commands. The values have the same meaning as the dt values found in XL2 log
files. If the parameter is unknown, a ";" is returned.
The unit (dB, dBu, dBV, V) is adopted by the setting of the user interface.

Page 56

XL3 API ManualControl API

MEASure:SLM:SPECtrum:RESolution
Alternative command keywords for XL2 compatibility: MEASure:SLM:RTA:RESOlution
ShortcutDefines the resolution in which the RTA results are acquired.

Availability

Sound Level Meter with run state = STOPPED

Parameter[ 1/1 | 1/3 | OCT | TERZ ]CHARDAT

Example

MEAS:SLM:SPEC:RES 1/3

MEASure:SLM:SPECtrum:RESolution?
Alternative command keywords for XL2 compatibility: MEASure:SLM:RTA:RESOlution?
Shortcut

Queries the resolution in which the RTA results are acquired.

Availability

Sound Level Meter[ 1/1 | 1/3 ]Answer
CHARDAT

ExampleDetails

www.nti-audio.com

MEAS:SLM:SPEC:RES?
1/3

The response of the alternative query returns the standard parameter keywords.

Page 57

XL3 API ManualControl API

MEASure:SLM:SPECtrum:WEIGhting
Alternative command keywords for XL2 compatibility: MEASure:SLM:RTA:WEIGhting
ShortcutDefines the frequency and time weighting in which the RTA results are acquired.

Availability

Sound Level Meter with run state = STOPPED[ AF | AS | CF | CS | ZF | ZS ]Parameter
CHARDAT
Example

MEAS:SLM:SPEC:WEIG CF

MEASure:SLM:SPECtrum:WEIGhting?
Alternative command keywords for XL2 compatibility: MEASure:SLM:RTA:WEIGhting?
Shortcut

Queries the frequency and time weighting in which the RTA results are acquired.

Availability

Sound Level Meter[ AF | AS | CF | CS | ZF | ZS ]Answer
CHARDAT

ExampleDetails

www.nti-audio.com

MEAS:SLM:SPEC:WEIG?
ZF

The response of the alternative query returns the standard parameter keywords.

Page 58

XL3 API ManualControl API

MEASure:RT60 Subsystem
MEASure:RT60?
Shortcut

Queries the average results of the RT60 analyzer

Availability

Reverberation time measurement function[ EDT | T15 | T20 | T30 ]Parameter
CHARDAT<results>
Answerarray of float
1/1 Oct: n = 8
1/3 Oct: n = 32
MEAS:RT60? T30
0.18,0.16,0.31,0.18,0.39,0.41,0.36,0.33 sec, OK

ExampleDetails

This command returns the average results. If no measurement has been started, theundefined value is returned. An average result is available when at least a cycle ismeasured. After each cycle, the intermediate average result is returned, and when themeasurement is terminated, the final average.
The number of values in the array depends on the selected octave resolution.

www.nti-audio.com

Page 59

XL3 API ManualControl API

MEASure:RT60:ATTR?
Shortcut

Queries the attributes of the average results of the RT60 analyzer

Availability

Reverberation time measurement function[ EDT | T15 | T20 | T30 ]Parameter
CHARDAT<results>
Answerarray of status characters
1/1 Oct: n = 8
1/3 Oct: n = 32
MEAS:RT60:ATTR? T30<,<,-,-,-,-,-,-

ExampleDetails

Each value in the values array has its status character in the second status array. The
characters have the following meanings:– ok, undefined< decay too short> decay too long
N low SNR
D insufficient SNR~ decay not linear
E errorwww.nti-audio.com

Page 60

XL3 API ManualControl API

MEASure:RT60:RESolution
ShortcutDefines the resolution in which the RT60 results are acquired.

Availability

always[ 1/1 | 1/3 ]Parameter
CHARDAT
ExampleRestrictions

MEAS:RT60:RES 1/1

The parameter 1/3 is only available if the Extended Room Acoustics Option is
installed.

MEASure:RT60:RESolution?
Shortcut

Queries the resolution, in which the RT60 results are acquired.

Availability

always[ 1/1 | 1/3 ]Answer
CHARDAT

Examplewww.nti-audio.com

MEAS:RT60:RES?
1/1

Page 61

XL3 API ManualControl API

MEASure:RT60:TRIGger:LEVel:MINimum
ShortcutDefines the minimum trigger level.

Availability

always<level>Parameter

NUM_L
Float value in dBSPL

ExampleDetails

MEAS:RT60:TRIG:LEV:MIN 80.0

The value must be in the range [-100 … +200]

MEASure:RT60:TRIGger:LEVel:MINimum?
Shortcut

Queries the minimum trigger level.

Availability

always<level>Answer

NUM_L
Float value in dBSPL

Examplewww.nti-audio.com

MEAS:RT60:TRIG:LEV:MIN?
80.0

Page 62

XL3 API ManualControl API

INPut Subsystem
INPut:PHANtom
Shortcut

Configures the phantom power setting.

Availability

When an ASD sensor is not connected.

Parameter[ OFF | ON ]CHARDAT

Example

INP:PHAN OFF

INPut:PHANtom?
Shortcut

Queries the phantom power setting.

Availability

always[ OFF | ON ]Answer
CHARDAT

Examplewww.nti-audio.com

INP:PHAN?
off

Page 63

XL3 API ManualControl API

CALIbrate Subsystem
The abbreviation CALI instead of CAL was only defined for compatibility with XL2 commands.

CALIbrate:MICrophone:TYPE?
Shortcut

Queries the sensor type

Availability

alwaysAnswer

STR

ExampleDetails

CALI:MIC:TYPE?
M4260

If no ASD microphone is currently connected, the command returns noASD

CALIbrate:MICrophone:SERIal?
Shortcut

Queries the sensor serial number

Availability

alwaysAnswer

STR

ExampleDetails

CALI:MIC:SERI?
1234

If no ASD microphone is currently connected, the command returns 0

CALIbrate:MICrophone:SENSitivity:VALUe?
Shortcut

Queries the microphone sensitivity in V/Pa

Availability

always<sens> V/Pa, OK

Answerfloats UNIT CHARDAT

www.nti-audio.com

Page 64

XL3 API ManualControl API

ExampleCALI:MIC:SENS:VALU?
20.0e-3 V/Pa, OK

CALIbrate:MICrophone:CIC

Shortcut

Switches M2340 microphones (and MA230 mic preamps) into self-test mode. The
microphone generates a reference tone (square wave with 31.25 Hz or 1 kHz), which
the XL3 can measure.

Availability

always[ OFF | F1 | F2 ]Parameter
CHARDAT
ExampleDetails

CALI:MIC:CIC OFF

To avoid CIC staying on (for example, if the remote connection breaks during CIC
measurement), CIC turns off automatically after 60 seconds. If you need the CIC signal
longer, retrigger the signal by sending the F1 or F2 command again within 60 seconds.
This command will fail and return with an error code if no sensor is connected or the
microphone doesn’t support this operation.

CALIbrate:MICrophone:TEMPerature?
Shortcut

Queries the value of the integrated temperature sensor of the M2340 microphone.

Availability

always<temperature> DEG_C, OK

Answerfloats UNIT CHARDAT

ExampleDetails

www.nti-audio.com

CALI:MIC:TEMP?
23.7 DEG_C, OK

This command will fail and return with an error code if no sensor is connected or the
microphone doesn’t support temperature readout.

Page 65

XL3 API ManualControl API

SYSTem Subsystem
SYSTem:CONFiguration:JStream
ShortcutSends a configuration that is then written to the XL3

Availability

Run state = STOPPEDJSON stream

Parameter
QSTR, embedded in single quotation marks only
SYST:CONF:JS '{"SLM":{"spectrum":{"octres":"1/3"}}}'

ExampleThe transferred configuration may be the whole or partial configuration out of thecomplete configuration described in Available JSON Parameters (see page 69).
The JSON stream must be embedded in single quotation marks because a JSON
stream contains double quotation marks.
Details

Only the stated configuration values are changed if only a partial configuration is sent.
The XL3 retains all other existing configuration values.
If the JSON format is invalid, the command is rejected.
The parameter may contain all values (characters) except the message termination
character (LF, 0x0A).

SYSTem:CONFiguration:JStream?
ShortcutReads a complete system configuration and returns it as a JSON object

Availability

always
JSON stream

AnswerTEXT

Examplewww.nti-audio.com

SYST:CONF:JS?
{"SLM":{"spectrum":{"octres":"1/6","hold…………

Page 66

XL3 API ManualControl API

Details

Note: The returned JSON stream is not embedded in single quotes as it is required forthe command.
The system configuration is described in Available JSON Parameters (see page 69).

SYSTem:CONFiguration:JStream:ERRor:TEXT?

Shortcut

Returns an additional error text if the last SYST:CONF:JS command has returned
erroneously.

Availability

alwaysSingle quoted error text

Answer
QSTR
Assumed command for this example:
syst:conf:js '{"SLM": {"spectrum": {, "hold_time": "3 sec", "fwtw":"ZF"}}}'

ExampleSYST:CONF:JS:ERR:TEXT?
'Missing a name for object member.|ectrum": {, "hold_time": "3 se'

Details

The error text consists of two parts where the second may be empty: specific JSON
parser error and JSON stream excerpt. A pipe character separates the two parts.
The error text is empty if the last command was successful or never executed.

SYSTem:CONFiguration:JEncoded
ShortcutSame as SYSTem:CONFiguration:Stream with the parameter encoded in base64

Availability

Run state = STOPPEDBASE64 unquoted string

Parameter
STR

Examplewww.nti-audio.com

SYST:CONF:JE
ewogICAgIlNMTSI6IHsKICAgICAgICAic3BlY3RydW0iOiB7CiAgICAgICAgIC…………

Page 67

XL3 API ManualControl API

Detailssee SYSTem:CONFiguration:Stream

SYSTem:CONFiguration:JEncoded?
ShortcutSame as SYSTem:CONFiguration:Stream? with the answer encoded in base64

Availability

alwaysBASE64 unquoted string

AnswerSTR
SYST:CONF:JE?
ewogICAgIlNMTSI6IHsKICAgICAgICAic3BlY3RydW0iOiB7CiAgICAgICAgIC…………

ExampleDetails

The system configuration is described in Available JSON Parameters (see page 69).

www.nti-audio.com

Page 68

XL3 API ManualControl API

Available JSON Parameters
The XL3 can be configured using JSON and the commands SYSTem:CONFiguration:JStream ,SYSTem:CONFiguration:JEncoded , or SYSTem:CONFiguration:FILE:LOAD

A complete list of available configuration parameters can be found in the /media/Configurations/documentation.txt file. This file is automatically created when the XL3 starts up.

SYSTem:CONFiguration:FILE:LOAD
Shortcut

Instructs the XL3 to load a configuration into the XL3 from a specified file

Availability

Run state = STOPPED
file nameParameter
QSTR
SYST:CONF:FILE:LOAD “<filename>”

ExampleDetails

The file /media/Configurations/<filename>.xl3cfg must exist and follow theConfiguration File Format (see page 69). You may upload the file using the
SYSTem:FILE:WRITe command.

Configuration File Format
A configuration file must have the extension .xl3cfg.
The configuration file consists of a header and a configuration data part. These two parts are divided by theseparator row ##CONFIG:
Each part is JSON formatted.
”MeasurementID”: [SLM|RT|SI] instructs the XL3 which screen to show
• SLM - Sound Level Meter• RT - Reverberation Time
• SI - Sound Insulation”UUID”: a Universal Unique Identifier

www.nti-audio.com

Page 69

XL3 API ManualControl API

Example content of a <filename>.xl3cfg:{"MeasurementID": "SLM","UUID": "00000000-0000-0000-0000-000000000000"}##CONFIG:{"SLM":{"spectrum":{"octres":"1/3"}}}

SYSTem:CONFiguration:DOCumentation

Shortcut

Creates media/Configurations/documentation.txt, which contains all configuration
options available with the current FW

Availability

always
SYST:CONF:DOC

ExampleDetails

documentation.txt is formatted as JSON pretty

SYSTem:FILE:WRITe
Shortcut

Writes the data to the file given by its pathname

Availability

always<file_pathname>, <base64 encoded data>

Parameter
QSTR, STR

Examplewww.nti-audio.com

SYST:FILE:WRIT “<file_pathname>”,ewogICAgIk1lYXN1cmVtZW50SUQiOiAiU0xNIiwK...

Page 70

XL3 API ManualControl API

Details

The relative file pathname is extended to the full pathname /media/<file_pathname>.
The folder separators may be slashes ('/') or backslashes ('\').
The first folder in the <file_pathname> (e.g. <SdCard1> or <Configurations>) must exist.
Note that the names are case-sensitive.
All following subfolders and the file are created if they don’t exist. The filename must
include the desired extension. An existing file will be overwritten with the new data.
The binary file data must be passed as a base64 encoded string.
The length of the entire command must not exceed 16k characters. This limits the filesize to 12k bytes.

SYSTem:FILE:READ?

ShortcutReads the data from a file given by its pathname and returns it as base64 encoded
stringAvailability

always<file_pathname>Parameter
QSTR<base64 encoded data>
AnswerSTR
SYST:FILE:READ? “<file_pathname>”

ExampleDetails

The relative file pathname is extended to the full pathname /media/<file_pathname>.
The folder separators may be slashes ('/') or backslashes ('\').
The file \media\<file_pathname> must exist. Note that the names are case-sensitive.
The maximum length of the file to be read out is 12k bytes. Reading larger files will
generate an error.

SYSTem:POWer:SOURce?
ShortcutReads the source of the power

Availability

always[ NONE | USB | WALL_ADAPTER ]Answer
CHARDAT

www.nti-audio.com

Page 71

XL3 API ManualControl API

SYST:POW:SOUR?
WALL_ADAPTER

ExampleDetails

If the XL3 is powered with both a wall adapter and a USB power supply, the wall adapter
is returned by this query.

SYSTem:SOH?
ShortcutReads the given State of Health items

Availability

always[ TIMESTAMP | VDCIN | BATTERYSOC|RUNSTATUS|WEATHERSTATIONS|FREESTORAGE|GPSLOCATION|
IPHANTOM|LOCALTIME|TIMEZONE|TEMPERATURE|AIRPRESSURE|POWERSOURCE|

Parameter

CLOCKSOURCE]

CHARDATSYST:SOH? LOCALTIME,GPSLOCATION
2024-02-09 14:57:20;47.174349 9.513426

ExampleDetails

Returned items are separated by semicolons if more than one is requested. Itemnames (parameters) are equal to these used for streaming. Also the format of the
returned items is equal to the streaming.

Restrictions

The maximum of parameters is 10. So, to query all items two separate commands are
required.

SYSTem:OPTIons?
ShortcutReads the installed options

Availability

always<options list>

Answerlist of CHARDAT

www.nti-audio.com

Page 72

XL3 API ManualControl API

SYST:OPTI?
FO, EN, ER, IN, NC, AP, DX, RA, SI, LW

ExampleDetails

The list contains the acronyms for the options:• FO - Full Option Pack
• EB - Environmental Noise Bundle• IB - Sound Insulation Bundle• RB - Room Acoustics Bundle• EN - Extended Noise Measurement• ER - Extended Room Acoustics• IN - Sound Insulation• NC - NTi Connect Open Data
• AP - API (Programming Interface)• DX - Data Explorer SW• RA - Room Acoustics Reporter SW• SI - Sound Insulation Reporter SW• LW - Sound Power Reporter SW

SYSTem:ERRor?
Shortcut

Queries the error queue

Availability

alwaysAnswer{errnon,}
NUM_L
n 50

Examplewww.nti-audio.com

SYST:ERR?
40, 70
SYST:ERR?
0

Page 73

XL3 API ManualControl API

 XL3 Error codes differ from XL2 Error codes
Details

There are different classes of errors. Some errors refer to the command syntax, others
to internal states of the XL3. Refer to the Error List (see page 75) below
Every error is pushed into the error queue that must be queried to get the error number.
Several error numbers from unused parser features may be returned. These numbers
are not listed here.

www.nti-audio.com

Page 74

XL3 API Manual
Appendix

Appendix
Error List
NumberDescription

0

no error (queue is empty)

10

No input command to parse

14

Numeric suffix is an invalid value

20

Parameter of type Numeric Value overflowed its storage

30

Wrong units for parameter40

Wrong type of parameter(s)41Wrong format of a type of parameter(s)42Invalid value of parameter(s)50Wrong number of parameters

60

Unmatched quotation mark (single/double) in parameters

65

Unmatched bracket

70

Command keywords were not recognized

75

Data block declaration is invalid, e.g. given length is larger than the size of the provided data

80

Item numeric insertion is an invalid value

82

DESIGN ERROR: Too many item numeric insertions in parameter Spec83

No numeric insertion value found in the input item

85

Numeric insertion value expected by the translator

86

Value in numeric insertion must be positive (unexpected negative sign)

87

Value in numeric insertion must be integer value (no decimal separator / floating point)

88

Numeric insertion value is out of range

www.nti-audio.com

Page 75

XL3 API Manual
Appendix

NumberDescription

90

No numeric suffix value but expected

91

Numeric suffix value is out of range

150

Invalid Date Time Format

151

Content of Date Time input is invalid

200

IMPLEMENTATION ERROR: Called translator doesn't fit to the declared parameter list in the
specs

201

IMPLEMENTATION ERROR: Called translator doesn't fit to the specific parameter
declaration

202

IMPLEMENTATION ERROR: Parameter index is out of range

203

DESIGN ERROR: At least the first parameter must be defined as required in the param spec

204

IMPLEMENTATION ERROR: Requested parameter is not implemented in the local query
function

300

Timeout while waiting for response message from core

301

Timeout while waiting for response message from core (configuration channel)

302

Timeout while waiting for response message from core (configuration channel)

303

Timeout while waiting for mirror update (configuration channel)

310

Requested broadband signal is not available (gliding eq or percentile)311

Requested spectral signal is not available (percentile)

350

Input verification: The ASD Hex-stream is not valid

351

Input verification: The JSON input stream is not valid (see JSON parser error for details)

352

Input verification: The BASE64 input stream is not valid

353

Input verification: The JSON input stream is empty

370

Invalid configuration file header

371

Unexpected empty configuration file header

400

IMPLEMENTATION ERROR: No command handler specified for this command

www.nti-audio.com

Page 76

XL3 API Manual
Appendix

NumberDescription

401

Access to uninitialized mirror data

402

Invalid parameter passed to command handler (e.g. unexpected value for query)403

Failed to translate parsed command parameter from the ParamSpec list into internal
enumeration type

410

DESIGN ERROR: Dynamic downcast to branch/leaf failed

411

IMPLEMENTATION ERROR: Invalid parameter in deserialization (should never occur)

420

Input verification: The JSON input stream is not a valid object

450

API option required to executed this command

550

RUNTIME ERROR: File I/O error

551

RUNTIME ERROR: File buffer memory error

552

RUNTIME ERROR: File I/O: unexpected content

560

Value input verification: Invalid enum value (not in list)

561

Value input verification: Enum type is not text

562

Value input verification: Float type is not a number

563

Value input verification: Signed integer type is not a number

564

Value input verification: Unsigned integer type is not a number

565

Value input verification: Value is not a text

580

Invalid path or file name581

Path is not relative (starts with ‘/' or '\’)

582

Path contains inexistent drive or media

583

Relative path is too long (exceeds internal buffer size)

584

Failed to create path585

File I/O: Failed to create file for write operations

586

Input is an invalid base64 encoding string

www.nti-audio.com

Page 77

XL3 API Manual
Appendix

NumberDescription

587

File I/O: Error while writing data to file588

Specified file not found589

File is too large for read operation

590

File I/O: Failed to open file for read operations591

OS call has unexpectedly failed

600

Failure while handling response message received from the core

601

Message received from the core does not contain valid RT data

700

WARNING: Not all elements in configuration were handled (unknown or misspellt),
configuration was loaded

750

IMPLEMENTATION ERROR: Not further specified error during execution (parsing, translation,
handling)

751

IMPLEMENTATION ERROR: Exception during error translation (exception due to unknown
error, recompilation with new generated code required)

800

Error queue overflow

810

Input buffer overflow

970

Program Lost Error

1001

Value is out of range

1002

Command rejected: Measurement is running1003

Not implemented

1004

Parameter is not available

1005

Request forbidden

1006

Internal memory error

1007

ASD device not present

1008

ASD page index out of valid range1009

ASD operation failed

www.nti-audio.com

Page 78

XL3 API Manual
Appendix

NumberDescription

1010

License required

1011(internal error) Attempt to load configuration parameter while not in loading state

1012

Configuration contains incomplete SLM limit setup

1013

Configuration file I/O error

1014

Memory error while processing configuration file1015

Configuration file format is invalid

1016

Configuration file header is invalid

1017

Failed to parse configuration

1018

Internal error: Timeout while waiting for load response

1019

Memory error while loading configuration

1020

Internal error: Unknown error

1021

Internal error: Error not further specified1022

The specified audio sample rate for recording is not allowed for compressed format

1023

Configuration load error: Specified Enum parameter not found1024

Configuration load error: Enum type mismatch

1025

Configuration load error: Float type mismatch

1026

Configuration load error: Signed Int type mismatch

1027

Configuration load error: Unsigned Int type mismatch

1028

Configuration load error: Text type mismatch

1029

Warning: The configuration file contains unknown entries

1030

Configuration load error: Selected accessory doesn’t fit to the connected microphone

1031

Configuration load error: Selected diffuse field correction doesn’t fit to the connected
microphone1032

The connected sensor (microphone) doesn’t support the current operationwww.nti-audio.com

Page 79

XL3 API Manual
Appendix

NumberDescription

1033

There is no sensor (microphone) connected1034

The current sensor (microphone) operation has failed

1035

Measurement Series is active

1036

Microphone is disconnected1037

The preamplifier is not supported

1038

Unexpected change of preamplifier1039

The preamplifier doesn't fit to the data from NTi server

1040

Updating Mic Model Number failed

1041

Updating Capsule Type failed

1042

Updating Microphone Sensitivity failed

1043

Unexpected change of the connected adapter

1044

Update to CS011 model number not allowed for this adapter

1045This adapter model doesn’t support writing a new serial number

1046

Failed to update the serial number

1047

Measurement function is not Reverberation Time

1048

Measurement Series is enabled1049

Loading configuration failed: File not found1050

Loading configuration failed: Local operation active1051

Set system date/time not allowed

1052

Failed to set system date/time1053

Setting not supported

10000

Streaming: No data found

10001

Streaming: No requested signals available

www.nti-audio.com

Page 80

XL3 API Manual
Appendix

NumberDescription

10002

Streaming: Too many signals

10008

Streaming: Internal error (with specific error text)

10009

Streaming: Not further specified internal error

10010

History streaming: File access error

10011

History streaming: Failed to open file

10012

History streaming: Failed to close file

10013

History streaming: File error, failed to set position (file or cache)

10014

History streaming: File error, failed to set position (file or cache)

10015

History streaming: Attempt to set a file position out of valid range

10016

History streaming: Attempt to use an invalid file type

10017

History streaming: Attempt to read from an invalid file position

10018

History streaming: File header contains invalid data

10019

History streaming: (Armed) Stream closed due to log file error

www.nti-audio.com

Page 81XL3 API Manual
Appendix

List of symbols
List of symbols used in the command description.
SymbolDescription:

Colons separate keywords of an XL3 command.

[]

Square brackets enclose the list of available parameters, of which one must be selected.

|

A vertical line reads as a logical „OR“, i.e. this sign separates alternative parameters.

<>

Triangle brackets enclose the variable parameters that must be set for a user-defined value.

{}

Braces have the same meaning as triangle brackets, except that the enclosed parameters canbe included several times.

,

Commas separate arguments in an arguments list.

?

The question mark indicates a query.

()

Round brackets enclose comments.

Parameter Types
Type

Description

STR

Unquoted String

QSTR

String embedded in single or double quotation marks

CHARDAT

Character Data

UNIT

Unit character data

NUM_L

Numerical value: Integer or Float. With optional unit

BIN

IEEE488 Binary Data

JSON

An open standard file format

www.nti-audio.com

Page 82

XL3 API Manual
AppendixDifferences between XL3 and XL2
Difference

XL2

XL3

Line ending“CR LF”“LF”

Response to set commands(Command without “?”)no“LF” after command completionof set command

Multiple Commands separated bysemicolons

no

yes

Device access

Only local PC via USB virtualCOM port

Througha TCP (see page 9) socket ora WebSocket (see page 12) ora browser through NTi
Connect (see page 8)

Command Keywords

Short or any variant of the fullform

Short or complete long keyword
is required

Channel open

No response

On channel open, the XL3 sends
the Channel Identification
Message or a Password: prompt

Symbols for second and minute inparameters“, ‘

Symbols are replaced withwords “sec” and “min”

www.nti-audio.com

Page 83

XL3 API Manual
AppendixGetting Started with Python and PyCharm Community Edition
This appendix is designed to help new Python users get productive quickly by using PyCharm Community
Edition as their integrated development environment (IDE). Follow these steps to open an existing project,install the latest Python version, and add the websocket-client package required by the examples.

Installing the Latest Python Version• Visit the Python official website1.
• Download the latest version of Python suitable for your operating system.
• Run the installer and ensure that "Add Python to PATH" is selected before clicking "Install Now."

Installing PyCharm Community Edition• Visit the PyCharm download page.
• Choose the Community Edition and download the installer for your operating system.
• Run the installer and follow the on-screen instructions to complete the installation.

Opening an Existing Project in PyCharm• Open PyCharm from your applications menu or desktop shortcut.
• On the welcome screen, click on "Open."• Navigate to the directory where your example code is stored.
• Select the folder containing the project files and click "OK."Configure the Project Interpreter:• Once the project is loaded, go to File > Settings (or PyCharm > Preferences on macOS).
• In the left sidebar, navigate to Project: <project_name> > Python Interpreter .
• Click the gear icon next to the interpreter dropdown and select "Add."• Choose "System Interpreter" and select the newly installed Python version from the list.
• Click "OK" to apply the changes.

Adding the websocket-client Package• Go to File > Settings (or PyCharm > Preferences on macOS).
• Install the Package:• In the left sidebar, navigate to Project: <project_name> > Python Interpreter .
• Click the + button on the right side of the window to open the available packages window.
• In the search bar, type websocket-client.
• Select websocket-client from the list and click "Install Package."• Verify the Installation:

1 https://www.python.org/downloads/

www.nti-audio.com

Page 84

XL3 API Manual
Appendix• Ensure the package appears in the list of installed packages under your project interpreter.

Running the Example CodeRun a Python Script:• In the Project Explorer pane, navigate to the Python script you want to run.
• Right-click the script file and select Run '<script_name>' .
Debugging:• To debug the script, right-click the script file and select Debug '<script_name>' .
• Use breakpoints and the debugging tools provided by PyCharm to troubleshoot and inspect your code.

www.nti-audio.com

Page 85