Nexmosphere XZ-A40 User manual

1. General
The XZ Angle sensor determines its current orientation following the measurement of the angle relative to the X, Y and
Z axis. This sensor facilitates applications such as detecting the position of a door or valve, or detecting the transition
between orientations of a display (for example portrait to landscape). This document provides explanation of the available
functionalities and instructions on how to install and integrate the sensor into your digital signage installation.
The information in this document is created for users who are familiar with the Nexmosphere API and are able to control a
basic setup with a Nexmosphere API controller. If this is not the case yet, please read the general documentation on the
Nexmosphere serial API rst.
2. Product overview
The XZ Angle sensor is available in 1 model:
Nexmosphere
Le Havre 136
5627 SW Eindhoven • The Netherlands
T+31 40 240 7070
[e-mail]
PRODUCT MANUAL
XZ RANGE | ANGLE SENSOR
© 2023 Nexmosphere. All rights reserved. v1.0 / 04-23
All content contained herein is subject to change without prior notice
1
Table of content
1. General 1
2. Product overview 1
3. Functionalities and API commands 2
3.1 Angle measurement 2
  3.2Conguringandstoringorientationpositions 3
4. Installation requirements and guidelines 4
4.1 Connection Diagrams 4
4.2 Hardware integration guidelines 4
5. Settings 5
6. Quick test 6
XZ-A40
Angle measurement
✔
Congurable orientation positions
✔
The XZ Angle sensor continually measures its orientation angle. This angle is measured in three dimensions; it measures
the angle relative to the X, Y and Z axis. In this way, the exact orientation of an object or surface can be derived. The sensor
determines each of the three values relative to the gravity line(s). In the images below, these gravity lines are depicted in
red and the sensor's orientation line and the angle are depicted in blue. Furthermore, these images also visualize the three
dierentanglesthatarecontinuallymeasuredbythesensor.
XZ-A40
Side view
X°
Top viewFront view
Y°
Gravity (G(z)) Gravity (G(z))
Z°
G(x)
G(y)
G(y) G(x)

© 2023 Nexmosphere. All rights reserved. v1.0 / 04-23
All content contained herein is subject to change without prior notice
Nexmosphere
Le Havre 136
5627 SW Eindhoven • The Netherlands
T+31 40 240 7070
[e-mail]
2
PRODUCT MANUAL | XZ ANGLE SENSOR
3.1 - Angle measurement
When the sensor is connected, it will immediately start measuring the current orientation angle. Per default, the sensor will
send out an API command every time a change in the current angle with the X, Y or Z axis of the sensor is detected. This API
command has the following format:
3. Functionalities and API commands
The XZ Angle sensor provides the following functionality:
1. Angle measurement - determines the orientation of the surface it is adhered to
2. Conguring and storing orientation positions - trigger when certain orientation positions are reached
The following sections will cover each of these functionalities in detail. Please note that for each API example in this
document, X-talk interface address 001 is used (X001). When the sensor is connected to another X-talk channel,
replace the "001" with the applicable X-talk address.
X001B[O=+XXX,+YYY,+ZZZ] Example API messages
The measured angle relative to the X-axis is 67°.
The measured angle relative to the Y-axis is -110°.
The measured angle relative to the Z-axis is 5°.
X001B[O=+067,-110,+005]
These three values respectively represent the sensor's
angle relative to the X, Y and Z-axis. Every X, Y or Z value
has lower and upper boundaries of -180° and 180°.
Furthermore, when it occurs that one of the three
values is irrelevant for determining the orientation of
the sensor, this value will be outputted as ****. This
behavior will occur when two of the three values are
(close to) -180, -90, 0, 90 or 180. This means that the
sensor is oriented parallelly to either of the three XYZ
dimension planes. The third value will then be outputted
as ****. Also, see setting 9 and 10 on page 4.
XXX = X-axis angle -180 to +180 or ****
YYY = Y-axis angle -180 to +180 or ****
ZZZ = Z-axis angle -180 to +180 or ****
The sensor lays on a perfectly leveled horizontal
surface, for example a table top.
X001B[O=+000,+000,****]
Data requests
A trigger of the sensor's current angle can also always be
requested by sending one of the following API commands:
The reply will be identical to the triggered API messages
such as the examples listed on this page.
X001B[X?]
X001B[Y?]
X001B[Z?]
X001B[ALL?]
X001B[V?]
Request angle relative to X-axis
Request angle relative to Y-axis
Request angle relative to Z-axis
Request all three angles seperately
Request orientation in one command
X001B[O?]
Request raw vector values
When implementing this sensor, consider the following:
• To make the implementation of the sensor easier,
several dierent orientation positions can be
congured.Wheneverthesensorndsitselfinoneof
theconguredorientationpositions,atriggerwillbe
sent. See section 3.2 for more info.
• The sensor can also be set to only output the X, Y or Z
angles. This can be done by using setting 5 (page 6) to
change the trigger axis or by requesting the singular
values through sending any of the data requests
on the right. In both cases, the output will have the
following formats:
XXX = X angle -180 to +180
YYY = Y angle -180 to +180
ZZZ = Z angle -180 to +180
X001B[X=+XXX]
X001B[Y=+YYY]
X001B[Z=+ZZZ]
Example API messages
Orientation measured with 124° angle to X-axis
X001B[X=124]
Orientation measured with 87° angle to Y-axis
X001B[Y=087]
Orientation measured with 61° angle to Z-axis
X001B[Z=061]

© 2023 Nexmosphere. All rights reserved. v1.0 / 04-23
All content contained herein is subject to change without prior notice
Nexmosphere
Le Havre 136
5627 SW Eindhoven • The Netherlands
T+31 40 240 7070
[e-mail]
3
PRODUCT MANUAL | XZ ANGLE SENSOR
X = the current orientation position
X001B[P=X]
Example API messages
The detected orientation matches orientation position 6
The detected orientation matches orientation position 8
X001B[P=6]
X001B[P=8]
Conguring these orientation positions can be done by
xingthesensorinapreferredorientationandsendingthe
following API command to the sensor:
3.2 - Conguring and storing orientation positions
Instead of triggering on any change of the X, Y, or Z angles, this sensor can be set to trigger when certain orientation positions
arereached.Theseorientationpositionsarecompletelycongurable.Intotal,upto8dierentorientationpositionscanbe
stored. This output mode can be set by sending the following setting command:
The API commands for entering a certain orientation
position have the following format:
Set output mode to position change
X001S[4:1]
X = number 1-8
X001B[STORE=PX]
Sending this command ensures that the orientation
position that is currently held, is stored in slot PX.
Example API commands
Store current position as orientation position 1
Store current position as orientation position 4
X001B[STORE=P1]
X001B[STORE=P4]
These orientation positions can be cleared one by one by
sending the following command to the sensor:
X = number 1-8
X001B[CLEAR=PX]
Factory reset
The orientation positions, sensor sensitivity and all other
settings can be reverted back to their default factory
values by performing a factory reset.
X001B[FACTORYRESET]
This can be initiated by sending the following API
command:
X001B[CLEAR=ALL]
Example API commands
Clear orientation position 3
Clear all orientation positions
X001B[CLEAR=P3]
X001B[CLEAR=ALL]
Or cleared all at once by sending the following command:

© 2023 Nexmosphere. All rights reserved. v1.0 / 04-23
All content contained herein is subject to change without prior notice
Nexmosphere
Le Havre 136
5627 SW Eindhoven • The Netherlands
T+31 40 240 7070
[e-mail]
4
PRODUCT MANUAL | XZ ANGLE SENSOR
4. Installation requirements and guidelines
When integrating an XZ Angle sensor into your digital signage installation, several installation requirements and guidelines
need to be taken into account in order for the sensor to perform optimal and operate stable.
4.1 - Connection Diagrams
The XZ Angle sensor can be connected to any X-talk interface and is therefore compatible with all Xperience controllers.
Make sure the XZ Angle sensor is connected to the X-talk interface before powering the Xperience controller. Otherwise, the
sensor will not be recognized by the Xperience controller and no output will be provided.
Example connection to XC Controller Example connection to XN Controller
4.2 - Hardware integration guidelines
Installation with double sided tape
The XZ Angle sensor is typically installed using the
double-sided tape. Using this method, the sensor securely
mounts on any at surface, horizontal, vertical or slant.
The XZ Angle sensor should be installed in a dry and dust-
free environment. The tape is easily removable and non-
marking.
Double-sided tape
DC Power supply
XC
XN

© 2023 Nexmosphere. All rights reserved. v1.0 / 04-23
All content contained herein is subject to change without prior notice
Nexmosphere
Le Havre 136
5627 SW Eindhoven • The Netherlands
T+31 40 240 7070
[e-mail]
5
PRODUCT MANUAL | XZ ANGLE SENSOR
5. Settings
The XZ Angle sensor has multiple settings which determine the behaviour and output of the interface. The settings can be
adjusted by sending X-talk setting commands via the API. After a power cycle, the settings always return back to default.
X001S[1:1]
X001S[1:2]
Setting 1: Status LED behaviour
1. LED on
2.LEDo
3. LED on, blink at trigger (default)
4.LEDo,blinkattrigger
X001S[4:1]
X001S[4:3]
X001S[4:2]
Setting 4: Trigger mode
1. Trigger on position change (1-8)
2. Trigger on orientation change (def)
3. Trigger on both value/pos change
4. No triggers, use data requests
When set to 4:1, the sensor will trigger upon reaching one
oftheconguredorientationpositions.Atdefault(setting
4:2), the sensor will switch to triggering each time either
of the three angles (X, Y, or Z) changes with 5°. This value
can be adjusted, see setting 6. With setting 4:3, the
sensor will trigger on both angle changes and orientation
positions it has reached. When set to 4:4, the sensor will
not trigger automatically but will only respond to any of the
API commands for data requests (see page 2). For more
general info, please see section 3, page 2/3.
This setting can be used to adjusts the amount of
information each trigger holds. At default, the sensor
triggers on changes of all three axis and sends the values
of these axis together in one command.
X001S[6:X]
Setting 6: Sensitivity / Trigger bandwidth
Any number between 1-45
X is a value between 1-45 and its default value is 5. This
setting determines the sensitivity of the sensor. In other
words, the value of X determines how much either the X, Y
or Z angle of the sensor (in degrees) must change before
the sensor sends a new trigger. Furthermore, when the
sensor is set to trigger orientation positions, this setting
adjusts the lower and upper boundaries of a position.
These boundaries determine how close the orientation
of the sensor must match an orientation position before
sending a trigger.
X is a value between 1-100 and its default value is 20.
This setting applies to situations in which the sensor
is set to trigger on orientation positions. Usually, the
sensor will not trigger on an orientation position when
it is in motion and 'passes' this orientation position
without stopping on it. The value X determines the
threshold for when the speed of this motion is slow
enough for the sensor to send a trigger. The lower X is,
the lower the speed of motion needs to be for a trigger.
Vice versa, the higher X is, the higher the speed of
motion can be for the sensor to still send a trigger.
X001S[1:3]
X001S[1:4]
X001S[4:3]
X001S[5:1]
X001S[5:2]
X001S[5:5]
X001S[5:7]
X001S[5:6]
X001S[5:3]
X001S[5:4]
Setting 5: Trigger axis for value change
1. Trigger on X-axis change
2. Trigger on Y-axis change
3. Trigger on Z-axis change
4. Trigger on X-axis and Y-axis change
5. Trigger on X-axis and Z-axis change
6. Trigger on Y-axis and Z-axis change
7. Trigger on all 3 axis (default)
X001S[8:X]
Setting 8: Sample averaging
Any number between 1-20
X is a value between 1-20 and its default value is 8.
This setting determines the number of samples which are
averaged to calculate the sensor's output. The higher the
number of samples, the less responsive the sensor will be
to change, but also the more stable in case of challenging
environments. The lower the number of samples, the more
responsive the sensor will be to change. Please note that
typically this setting does not need to be adjusted.
X001S[7:X]
Setting 7: Motion lter
Any number between 1-100
Per default (9:1), this sensor will output **** when one angle
value is irrelevant for determining the orientation of the
sensor. This can be adjusted by sending the 9:2 setting,
which will set the sensor to always send the irrelevant
value. For more information on the irrelevancy of a value,
see section 3.1 on page 2.
X001S[9:1]
Setting 9: Show irrelevant axis
1. Do not show irrelevant axis,
show **** instead (default)
2. Show irrelevant axis
X is a value between 1-25 and its default value is 15. With
X, you can determine the lter level of an irrelevant axis.
In other words, at what point an axis is seen as irrelevant.
Here, the rule applies; the higher the value, the sooner the
sensor will categorize a value as 'irrelevant'. Please note
that typically this setting does not need to be adjusted.
X001S[10:X]
Setting 10: Filter level for setting 9
Any number between 1-25
X001S[9:2]

© 2023 Nexmosphere. All rights reserved. v1.0 / 04-23
All content contained herein is subject to change without prior notice
Nexmosphere
Le Havre 136
5627 SW Eindhoven • The Netherlands
T+31 40 240 7070
[e-mail]
6
PRODUCT MANUAL | XZ ANGLE SENSOR
6. Quick test
In order to test if the XZ Angle sensor is installed correctly, please follow the test procedure below:
Step 1 - Setup
Connect the XZ Angle sensor to an Xperience
controller, make sure that the XZ sensor is not
moving and power the Xperience controller.
The green status LED of the XZ should be lit
continuously. The status LED of the controller will start
to blink and once power-up is completed will be lit
continuously.
Step 2 - Test
Move the XZ Angle sensor around.
Both the green status LED of the XZ and the status
LEDofthecontrollershouldblinkeachtimeadierent
orientation is detected.
For a full test we recommend to connect the setup to
a mediaplayer or PC and test all API commands listed
in this document (see section 3, page 2-3). For more
information on how to setup a test for your controller,
please see the Quick Start Guide of the Xperience
controller you are using. These are available on
nexmosphere.com/support-documentation
Please contact [e-mail] for any
support questions you may have.
In case any of the steps above does not provide
the expected result, please check the installation
guidelines in this document.
XN
Connect to powered
USB port
XN
LED BLINK
LED BLINK