axium mobile application documentation
TRANSCRIPT
1
Axium Mobile Application Documentation
Most of this document is geared towards providing an overview on the usage of Axium Design Portal
with regards to the Axium mobile app. However, the Common Issues section describes some issues
that are possibly more relevant to the actual runtime of the mobile app itself.
Popups
Popups are a feature that allows a frame of content to be shown and hidden by the user. They are
useful for displaying confirmation or information dialogs and when displaying lists or selections that
are too complex to be displayed as a permanent fixture on the page itself. Popups will often be used
in combination with a Scroll Panel in order to display a large list.
To create a new Popup there are two common methods:
1. Right click the page designer and select Add new popup
2. Right click the popups list in the page properties and select Add Popup. From here you can
either create a new popup or add an existing popup to the page.
Once a popup has been created an empty frame will be added to the page. At this point the popup
can be sized and positioned like any other page item. Popups are unique however, in that if another
Method 1 – Right click page Method 2 – Right click popup list
2
page item is selected, the popup frame on the page will become invisible. This is a designer feature
purposed so that the designer UI does not become cluttered with layers of page items. To select a
hidden popup, go to the Popups list in the page properties.
To define the layout and contents of a popup, there are again, two methods:
1. Double click the visible popup on the page or popup list
2. Right click the popup in the popup list and select Edit
The popup layout designer is essentially the same thing as the page designer. Current limitations are
that a popup is unable to contain other popups and the swipe gesture actions are not yet
implemented.
To close the popup layout editor and to return to the page designer, click the green tick in the top
left corner of the designer toolbar.
Another essential part of adding popups to the layout design is to set up the triggers to show and
hide the popup. Commonly this is done as a button action but this can also be implemented as a
part of a macro. There are a number of ways to set a popup as an action depending on the
destination for the action.
1. Drag the popup from the popups list onto the desired button.
2. Right click an action box in the relevant properties dialog and select the popup from the
Popups submenu.
3. Right click the desired button and select the desired popup from the Link To Popup…
submenu.
Triggering the popup action will either show or hide the popup where appropriate. This allows a
button to act a toggle for the popup.
Aside from adding existing popups as action there are also two other popup actions which can be
set. These are Close All Popups and Close Popup. The Close Popup action can only be set when the
destination for the action is within a popup.
Scroll Panels
Scroll Panels are a useful feature which enables designing layouts to extend beyond the boundary of
the containing layout. This is important and useful for displaying lists or a large number of related
Figure 3 – Finish editing popup
3
page items which would ordinarily have to be spread across multiple pages in order to fit them in
the design. They are also aesthetically pleasing and a natural input method for touchscreen devices.
To create a new Scroll Panel, right click the page designer and select Add new scroll panel
The scroll panel layout editor follows the same principles as the page designer and the popup layout
editor. The scroll panel has additional restrictions to prevent adding popups or other scroll panels to
the layout of a scroll panel.
Scroll panels can be either vertically or horizontally orientated. This setting determines the axis of
the scrolling content. The content size boxes in the scroll panel properties define the size of the
scrollable area. One dimension will always be equal to the actual page item size while the other can
be larger. A vertical scroll panel’s content width for example must equal the page item width since it
does not scroll on that axis. Its content height however can be any value larger than the page item
width.
Paging is another useful feature of scroll panels. When
this option is selected, the behaviour of the scroll panel
changes so that the scroll is divided into segments or
pages, each with the width or height of the page item
depending upon the orientation. A non-paging scroll
panel on the other hand is free flowing and is more
suitable for displaying lists as opposed to layouts.
Figure 4 – Scroll panel properties
4
Landscape / Portrait Pages
Pages have three settings with regards to the page orientation: Portrait, Landscape or Both. Each
orientation must be designed for individually and normally each orientations page layout would
have comparable functions and items for consistency. Although the two orientations both logically
represent the same page, they are in fact separate pages so rotating a device will load the other
orientations page and clear any resources as needed from the last. This is important to keep in mind
when using applets with regards to the concept of applet instances. This will be described more in
the applets section.
The Portrait or Landscape pages can be added or removed at any time in the design process by
checking or unchecking the appropriate checkbox in the mobile app design settings. Bear in mind
that removing a set of pages is an operation that will not be able to be undone due to the magnitude
of the changes required.
To change between the orientations in
order to edit them, click on the rotate
page button in the Resources toolbar.
Scaling / Resizing designs
Layouts designed with Axium Design Portal can to some extent, be scaled to suit devices with various
screen sizes. There will inevitably be the need to manually position and resize certain items to suit
different devices, especially when the aspect ratio differs greatly from the original and the scaled
size. The primary advantage of scaling designs for supporting other devices is that all of the
programming aspect is retained.
There are two options when resizing configurations, Scale and Move. To access these options simply
change the target resolution of an existing design.
Selecting the Scale resize type will adjust the size of all page items, respecting the aspect ratio, to
the comparative size capable of fitting the new resolution. Note that the Font property on page
items is not scaled to match the new resolution. The font size will need to be adjusted manually to
suit the new size.
Selecting the Move resize type will simply change
the resolution of the layout and any page items
that are positioned outside the layout boundary
will be moved in order to fit. This option may be
a better choice if more fine-tuned handling is
required for the resolution change.
Figure 6 – Resize layout
Figure 5 – Rotate page
5
Animations
Animations are an option that is available for actions which either transition pages or show and hide
popups. They are set by performing a right click on the appropriate action in the relevant properties
dialog and selecting an appropriate animation from the Transition Animation submenu. In the case
of macros, the same procedure is followed but on the actual macro action listed in the macro
instead.
The None, Fade and Zoom options are
self-explanatory, but the Slide
animations have an alternate mode for
each direction. When using a Slide
animation the entry and exit behaviour
of the views must be defined. This is
presented in the animation selection
menu under two headings: Slide
Opposite Entry/Exit and Slide Same
Entry/Exit. When applying to a page
transition, the entry and exit directions
are applied to the entering and exiting
pages respectively. When applying to a
popup action, the entry direction is used
for showing the popup, and the exit
direction is used for hiding the popup.
Figure 7 – Set an animation for a page transition
6
Variables
Leveraging the use of variables in the Axium mobile app is a feature made available when utilising an
Axium Controller in the system. The usage possibilities for variables are vast and have applications
for scripting, reporting sensor feedback, and for providing state information for devices which don’t
report it themselves.
To add variables, select the New Variable toolbar button when configuring an Axium Controller
device in the project.
A variable can be one of three types:
1. Boolean - a simple flag with the value being either true or false.
2. Integer - a whole number. The Range property defines the minimum and maximum values
that the variable can be set to and only applies to Integer variable types.
3. String - a sequence of characters.
If the Read Only option is not enabled, variables may
be modified by the mobile devices when implemented
to do so, but if the variable is set to Read Only, the
variable may only be modified by the Controller itself.
There are no functions in the designer for a mobile
device to modify a String variable, so it is effectively
always set to Read Only.
Figure 8 – New variable
Figure 9 – Variable properties
7
The value of a variable can be presented on the
mobile app by adding the variable to the Variable
action property of a Button or Volume Box. In
the designer, Volume Box represents both sliders
and readouts.
A Boolean variable is toggled as the action unless
the variable is set as Read Only. The button’s
active state will reflect the value of the variable.
Setting a String variable to a slider will have no
effect. When linked to a button, the text value of
the variable will be displayed. Make sure that a
Font is selected.
When an Integer is added to a slider and the
variable is not Read Only, then adjusting the
slider will adjust the variable’s value. A button
however must set a button class from under the
Axium -> Variables submenu in order to modify
the Integer value. The following classes are
available:
0 .. 9. Sets the variable to the number indicated by the class. Button is also active when the
variable is equal to this number. These classes are best suited for a keypad input.
Increment. Increases the value of the variable by 1. Ideal for level and counter variables.
Decrement. Decreases the value of the variable by 1. Ideal for level and counter variables.
Figure 10 – Variable on button properties
8
Applet Design
Applets are mini applications which provide and enhance interaction with specific types of
equipment or services. The following is a list of currently implemented applets:
Axium Media Player
Integra Receiver
ReQuest
Sonos
Bticino Lighting
CBus Lighting
Vantage Lighting
ELK M1 Alarm
Schedule Event Setup
Variable Display
WebView
Each has its own unique properties and will be documented in its own section.
Applets are created by right clicking the layout designer, and selecting one of the listed applet types
from the Add new applet submenu. A frame for the applet is then placed onto the layout, which
contains a rudimentary display of how the applet may appear when it is used. Here are some
common properties across all applets:
Font – creates or selects the font used by
the applet for displaying text.
Text colour – selects the colour of most
text displayed by the applet.
Background colour – selects the colour of
the background when the transparent
option is not selected.
Transparent – selects between
transparent and opaque backgrounds.
Device – selects the device to be
controlled by the applet. Depending on
the applet, the device may be either IP
based or RS232 based. When an IP device
is used the mobile device will directly
communicate with the device in question,
whereas if an RS232 device is used, an
Axium Controller will delegate on behalf
of the mobile device.
Figure 11 – Add new applet
9
The concept of applet instances is an essential part of the way applets are managed and function.
Two applets frames with the same instance share the network connection and the execution state of
the applet. Two separate frames on the other hand will not share anything between each other.
Whenever applets are to be spread across multiple pages or orientations, they should be the same
instance to ensure that the state and connection of the applet is retained upon a page transition. If
the same applet instance is not present on a new page, then the applet will be closed and all
resources freed. This will impact the user experience due to overheads and connection delays if not
designed for properly.
Some applets such as Integra Receiver and Sonos, can use
multiple instances of an applet on the same page. These are
unique and this should not be done for other applets or the
behaviour governing which is used and displayed is undefined.
The Sonos and Integra applets use the applet instance on another
level, associating it with different modes making this possible.
Look at specifics in their respective sections.
Applets can be morphed into existing instances of the same
applet type by selecting an entry in the Applet drop down box in
the applet properties. There you will also have the option of
converting the applet into a new instance, copying the current
properties as a template for the new instance.
Applets are identified by what applet instance they are; by
checking the name and core properties of the applet.
Most applets rely on or at least complemented by buttons, sliders and readouts. Buttons have a
Class property which when set to an entry from the Applets submenu, causes the button to belong
to the applet instance of that type on the layout. The instance is automatically chosen based on the
type of applet, but in rare cases there may be multiple instances of the same applet on a page. In
this case the button must be positioned within the frame of the applet in order for the button action
to be recognised as for that specific applet. Sliders and readouts use this technique as their only
means of determining which applet they are assigned to.
The class of a button defines what action that button will have with regards to the applet. Any
action associated with the class is performed on the release event of a button.
Figure 12 – Changing the instance of an applet Figure 13 – Renaming applet
10
There are many examples of the various applets and their associated buttons and sliders in the
Applet Examples Hires gallery.
Performance considerations:
In ordinary circumstances the applet will close when a page transition occurs and the applet is
determined to not exist on the new page. The result of this is the applet needing to reconnect again
when going back to the page with the applet, in addition to any state that the applet was in being
lost. A common design approach when using applets is to make the applet persistent across some or
all pages of a design. The purpose of this is to retain the applet state and/or prevent the costly
loading times where the applet initially connects to the device it is controlling.
In order to setup applet persistence across pages without requiring the applet to display content on
a page, the applet frame should be sized down to be as small as possible. When the applet frame is
sized 20px or less in any dimension it will be set to a mode which will prevent rendering which saves
resources as well as stopping undesired artefacts on the screen. When available, the applet frame
should also be set to a view mode which will not ordinarily perform drawing. Examples of this are
the “Lite Version” option for the Integra Receiver applet, the “Volume Frame” view type for the
Sonos applet, and the “No Display” view type for the Scheduled Event Setup applet. The reason for
this is largely a matter of principle but also because the internal logic of the applet might take into
account which applet frame types are available during its processing. By choosing the view type
which does not display anything, the applet execution may be done more optimally.
11
Axium Media Player
The Axium Media Player applet is a straight forward media player implementation. It does not use
the device property like many other applets do; instead it directly uses the amplifier used by the
design in the project. In order for the applet to function correctly, the zone of the applet must have
its current source set to Media. For this reason the Axium Media Player applet is typically situated
on a page accessed by a button which sets the source to Media before loading the page.
The media shares to be listed by the applet are
defined in Amplifier Settings -> Media Servers.
The username and password must match an
account which has access to the share. For a
share that everyone has access to, the default
username guest and a blank password are
normally used.
Figure 15 – Axium Media Player
Figure 14 – Axium Amplifier Media Servers
12
Integra Receiver
The Integra Receiver applet allows controlling as well as receiving metadata and feedback from
Integra AV Receivers. In many cases only the control functionality is required; in such cases the Lite
Version box should be checked. When in this mode, the applet will function as normal but the
applet will not display anything. It is possible with the Integra applet to mix 2 applet frames of the
same applet instance on a single page when one of the frames has the Lite property set. This is very
useful in the case where metadata is desired but a volume control or readout is required that is
unable to be positioned in a location within the boundary of the standard applet’s frame.
Figure 16 – Integra applet
Figure 17 – Integra Lite applet
13
Figure 18 – Sonos properties
Sonos
The Sonos applet is a more advanced applet that requires some setting up in order to achieve a
working solution. Firstly unlike other applets, the Device property does not need a port number
associated with it. The IP address / URL is the only required field for setting up this device. The
Sonos device itself should be configured and set up using the standard Sonos software prior to
attempting to use this applet for control.
Another point of difference with the Sonos applet is that its various functionalities are presented by
using four different view types:
1. Now Playing
2. Queue
3. Content Browser
4. Volume Frame
In order to achieve complete functionality, the first
three of these types will need to be used in the design,
and all need to be the same applet instance. Refer to
Applet Design for more on this. The volume frame
offers more fine-grained control over the positioning of
any volume control or readout.
The different view types may be mixed and matched
together or separately, across a single page or several
pages; there is no limitation on this. One important
thing to note is that some functionalities of a view type
require the other view types to be activated, which
may not initially be the case when the applet frames
are spread across multiple pages. For this reason
adding the three view types together on the same page
encapsulated by a scroll panel or a few popups is
recommended. This way all applet frames are
initialised together and no functionality will be missing.
14
Currently the Sonos applet supports three external services: Spotify, Pandora, and MOG. These
services need to be configured using the Sonos setup software prior to using them with the applet.
Each service can be added by enabling it and entering the authentication details for the account in
the Services tab of the Sonos properties. These details are encrypted and are secure. They are
required in order for the mobile device itself to connect to the service; the Sonos device will have its
own setup details for its interactions with these services.
The button classes for the Sonos applet are organised
within four groups, which pertain directly to the view
types.
Navigator Up through to Back, are used to control the
Content Browser view type.
Playlist Up through to Select, are used to control the
Queue view type.
Play through to CrossFade, are used to control the Now
Playing view type.
Figure 20 – Sonos button classes
Figure 19 – Services tab in Sonos properties
15
Grace Reciva
The Grace Reciva applet is very similar to the Sonos applet. One exception of note is the lack of the
Services tab. This is because the services are configured and handled by the Grace Reciva internally
so in theory all available services should be controllable once set up correctly.
Apple TV
The Apple TV applet is also very similar to the Sonos applet. The applet is limited to controlling the
iTunes database present on the Apple TV, and not any other externally shared libraries. In addition
to playback control and feedback, the applet provides button classes which cover all the
functionality provided through the IR remote.
The applet includes a
Setup function which is an
essential step to take
before any control of the
Apple TV is possible. First
set a unique Controller ID
in the applet which is
associated with the device
controlling the Apple TV.
If the same layout is
uploaded to more than
one device, only one may
control the Apple TV at a
time. For this reason you
should upload to each device with a different Controller ID, completing the setup
procedure for each ID used. Another note to bear in mind is that only one remote may be used to
control the Apple TV on a single device at a time. This means that you cannot have both the iOS
Remote app and the Axium app open at the same time.
Figure 21 – Configure Apple TV
Figure 22 – Waiting for the pairing to complete
16
For advanced purposes the applet can be used to allow control of an iTunes library instead of an
Apple TV. The features available in this mode are the same to those of the Apple TV feature set.
Roku
The Roku applet is an extremely simple control applet. Due to the limitations of the control API
there is no 2-way feedback, but it does offer support for using the mobile device’s keyboard instead
of using cursor controls to input text.
ReQuest
The ReQuest applet is a simple media player applet similar in functionality to the Axium Media
Player applet. Due to constraints imposed by the ReQuest control API, the playlist is not scrollable.
Vantage Lighting
The Vantage lighting applet brings simple integration of lighting control. The configuration is very
straightforward which mostly involves setting the appropriate VID and any options for tasks.
Bticino Lighting
The Bticino lighting applet allows for simple lighting control. Some set up is required on the Bticino
side to enable control via this applet. Refer to the Bticino documentation regarding “IP address
enabling mode” for more information.
17
CBus Lighting
The CBus lighting applet offers more complex lighting
control. The applet setup is fairly straightforward with
some configuration options available to cater for more
advanced purposes.
When using the CBus lighting applet it is recommended
to use an RS232 - CBus PC Interface connected to an
Axium Controller as the device for the applet. This is
opposed to the option of using the Ethernet interface for
CBus. The reason for this is that the CBus Ethernet
interface only allows one concurrent connection and
does not correctly detect when a used client
disconnects. This makes for the very real possibility of
complete loss of control in these circumstances. The
issue is compounded by the fact that the mobile devices
use Wi-Fi to establish Ethernet connectivity and any drop
in connection could trigger this serious problem to occur.
Note: There is a bug and/or limitation with CBus where
any GA which is purely virtual in nature, will be reported
by both the CBus PC Interface and the Network Interface
as non-existent. To work around this issue we
recommend creating a board with dummy physical components so that CBus integration
components will correctly return the status of the group address.
Lutron Lighting
The Lutron lighting applet is another complex lighting applet. The features available through the
applet are comprehensive and also cover basic temperature control, sensor states, blinds and
shades. In order to properly configure the layout, some familiarity with the Lutron designer
software will be required in order to understand the configuration options available.
The Integration ID is set for every action. It is either the ID of the output or the device depending on
the type of button class which sets it. The generic ‘Button’ button class is used for buttons that are
available on the device the ID is for. These buttons are most often ‘Phantom’ buttons which are set
up in the Lutron designer to perform a special action. There are many different configuration
options and combinations which are presented depending on the button class that they are
associated with. Once the context of the button class is understood, the options for these should be
self-explanatory.
Figure 23 – CBus properties
18
In the applet properties window, there are two tables
which should be filled out to represent the mappings
of Integration IDs to devices, and the Component
Numbers respectively. These settings are not always
necessary, but depending on the combination of
devices and features used, sometimes the applet
needs to be able to distinguish the type of device and
Integration ID represents or to enable button active
states for ‘Phantom’, ‘Dynamic’ or ‘Custom’ set button
actions.
Figure 24 – Lutron properties
Figure 25 – Lutron ‘Component Number’ table
19
ELK M1 Alarm
The ELK M1 Alarm applet is a straightforward applet to manage ELK and Ness M1 / EZ8 alarm
systems.
The Area property defines the area which the applet will control. Only zones that are associated
with this area can be controlled by the applet. If more areas are needed to be controlled then an
additional applet instance will be required for such handling.
The Baud rate property is used when using rs232 serial as the means of connecting an Axium
controller to the alarm system. The value should match whatever the alarm system is set up for. If
IP control is used then the value of this property is irrelevant.
The Pin Length property must match the size of the
configured pin code for the alarm. When the
number of required digits is entered with the
button classes 0 to 9, the arming operation or any
other privileged operation that is being performed
will be sent to the alarm system to handle.
The Temp. unit property is used in conjunction with
any buttons using the Zone temperature button
class which outputs the sensory information from a
temperature sensor probe configured as a specific
zone.
Figure 26 – ELK alarm properties
20
Variable Display
The Variable Display applet is a rather unique applet type
offering flexible presentation and design possibilities. The
purpose of this applet is to display information related to
the values of variables. This is achieved by using HTML to
define a layout and using the javascript library sprint.js to
provide simple manipulation of data into various formats.
Variables are added to the applet by dragging and dropping
a variable from an Axium Controller onto the variable
display properties grid. The tag of the variable is given
which is the array name and index used in the user defined
script in the HTML layout.
Since this applet is HTML based the applications of this
applet are vast and extend beyond the purposes if solely
displaying variables. This applet could be used for example
to display animated GIF images, which are otherwise
unsupported. The Enable Interaction option will allow for
the user to interact with the html as an ordinary webpage allows.
Figure 27 – Variable Display properties
Figure 28 – Editing the source HTML for the Variable Display
21
WebView
The webview applet enables the Axium mobile app to access URL resources. The content could
range from a web page to images and videos. A common application for this applet is to display live
streams or updates from IP cameras and web cameras. The Mode property of the webview has four
options which are tailored toward providing the most optimal experience and efficiency depending
upon the type of content. The modes are:
1. Default WebView - a standard web browser control which offers a full web experience.
Useful for navigating websites and streaming videos.
2. Static Page - a standard web browser control but with no user interaction. Great for
displaying a page and restricting navigation and input.
3. URL Image - a lightweight image display. The most efficient way to display a static image.
4. MJPEG Stream - similar to URL image, but used for a
stream of motion JPEG images which is a common
format for IP cameras.
The Auto Refresh property defines the frequency for which the
webview will perform a refresh of the content. When MJPEG
Stream is used, this is the frame rate for the stream.
The Action property allows a non-default webview to register
a press or release functionality. This can be useful for example
to display thumbnails of a web camera image, and have the
action display a larger version of the image.
Figure 29 – WebView properties
22
Scheduled Event Setup
The scheduled event setup applet creates the provision for
manipulating scheduled triggers. These triggers are created
on an Axium Controller and have much functional flexibility
with features including repeats, secondary actions,
sunrise/sunset offsets, and customisability for the days of
the week on which the trigger will occur.
Each time or offset input field is designed by implementing
multiple applet containers each representing the same
applet instance. The View Type property for each container
is set to define which input field to display. The No Display
view type is a special type with no functionality. It is useful
for defining which page items are affiliated with a particular
applet instance. This is essential when designing a layout
with multiple applets instances on a page.
When the view type is set to either ‘From/At Offset’,
‘Until/Off Offset’ or ‘Repeat Interval’, then the Unit
property will become available to set. This property defines
what measurement of time to use when displaying the
value. The same property should be set on the affiliated
button class used to increment or decrement the value.
Figure 30 – Scheduled Event Setup properties
Figure 31 – Scheduled Event creation
23
Scripts
Scripting is a powerful feature available on Axium controller devices such as the R1 and R4. The
possibilities available through the use of scripting are vast and extend beyond the scope of this
document. Some popular scripts for integrating with Axium systems are covered in the following
subsections. These scripts will be available for download along with a test project from
http://www.axium.co.nz/Downloads/Scripts
The most basic integration for scripts into a project is by linking the script to a set of variables. These
variables are then linked to page items on the layout design which can act as both the means of
state feedback and control. The script can monitor changes to the variables, and upon such
occurrences, update an external device appropriately. The inverse is also true, whereby the script
receives data from an external device it will update the variables. This design approach effectively
turns variables into the ‘glue’ between an external device and the control device.
Refer to the Variables section for more information on integrating variables with page items.
CYP AU- A300
This CYP script implements simple 2-way control for the Power, Mute, Source and Volume
components of a CYP amplifier. It supports connectivity via IP and RS232. RS232 could be
considered the preferred connection type because the IP mode has additional overheads which
require more processing and a larger stack size to handle. See the notes in the script for additional
information.
To change the type of communications used to control the device, drag the RS232 or IP device from
the Project Viewer over the first item in the script’s object list. Also, modify line 26: #define
ETHERNET false. Set to true or false accordingly.
Denon/Marantz
This is a slightly more complex example which provides 2-way control for a single zone of
Denon/Marantz AV Receivers. Multiple instances of the script may be run in order to provide multi-
zone control and feedback.
To change the zone that the script is to manage, modify line 26: #define Zone 2.
To change the type of communications used to control the device, drag the RS232 or IP device from
the Project Viewer over the first item in the script’s object list.
Depending on the model and make, some features may not work out of the box. The most notable
and probable of which would be the variety of available sources. The source definitions can be
24
modified to enable this support if the command protocol for the make/model is known. The
following line numbers are the locations where modifications will be necessary:
At line 33: enum t_source
At line 204: static String:get_source_str(t_source:source) {
At line 450: static handle_source_str(String:str_data) {
There are 9 variables used by this script:
1. AMP Power ( Boolean )
2. Zone Power ( Boolean )
3. Mute ( Boolean )
4. Volume ( Integer ) ( RANGE: 0 - 196 )
5. Volume_Percent ( Integer ) ( RANGE: 0 - 100 )
6. Surround ( Integer ) ( RANGE: -1 - 9 )
7. Sources_0_9 ( Integer ) ( RANGE: -1 - 9 )
8. Sources_10_19 ( Integer ) ( RANGE: -1 - 9 )
9. Sources_20_29 ( Integer ) ( RANGE: -1 - 9 )
The Volume_Percent variable is used by the increment and decrement buttons so that the volume
steps by a percentage point each time.
The Sources_X_X variables provide feedback and control for up to 10 sources each. The reason this
functionality is split amongst several variables is so that the button classes Variables -> 0 .. 9 will
correspond to these values and show feedback on the currently selected source. The correlation
between the sources and these classes can be found at line 33: enum t_source
The Surround variable functions in the same manner as the sources, but may not be fully
implemented to the extent required for a drop in functionality. It is intended that the script be
modified to handle the specific surround modes that need to be controlled. Normally the various
surround modes that are used will be fewer than 10 distinct modes, but if not then the surround
handling will need to be changed in order to function in the same manner that the sources are
handled - by using multiple variables to handle 10 states each.
25
NAD Receiver
The NAD Receiver script is a simple 2-way control script for Power, Mute, Source and Volume. Both
IP and RS232 control are supported.
To change the type of communications used to control the device, drag the RS232 or IP device from
the Project Viewer over the first item in the script’s object list.
Q-Sys Core
The Q-Sys Core script can be complex and requires careful mapping of components in the Q-Sys
design software to the variables and name standard chosen for the script. The primary difficulty
with this script arises because of the dynamic protocol that Q-Sys uses to control and get feedback
from components. The example included implements control of 4 inputs in each of 6 zones. Each
zone and input has control of volume and mute status.
To change the authentication/login details, uncomment and modify line 33: #define login “Joe
1234”.
The Change Group and Polling time of the connection can also be configured by modifying these
define instructions at the beginning of the script.
26
Upload Procedure
The process of uploading a design to a mobile device involves
two phases.
1. Discovery - When the upload toolbar button is clicked,
a popup windows is displayed which will list devices
running the Axium app that are found on the network.
The mobile device must be in Update Mode which will
make it respond to the discovery broadcasts of Axium
Design Portal. The mobile device will respond every
time the app is entered or refocused while the upload
popup window is open.
2. Upload - When a device is selected and the Upload
button on the popup window is clicked, the actual
upload will commence.
The Axium mobile app supports multiple configurations to be stored on the device. Pressing the
Options button will show the available upload slots. Selecting any numbered slot will overwrite any
existing design stored there, and selecting the New slot will add an additional configuration to the
device.
Having multiple configurations on a device is useful if the device is used on more than one site with
an Axium Audio/Control system. By default the app will have an automatic loading procedure to
determine which configuration should be loaded. This works by detecting all Axium amplifiers on
the currently connected network and cross-checking these with any amplifiers used in the
configurations on the device. In this way the app will load a configuration as appropriate depending
on the location and network.
Some iOS devices have an option for ‘Zooming’ the display interface. It in fact actually uses a
different screen resolution and scales to the panel size. This means that on such devices an
additional configuration for both screen resolutions should be stored on the device so that the user
can switch modes according to their preference. The app will detect correct configuration based on
the screen resolution.
Figure 32 – Upload box
27
FAQ / Troubleshooting / Common Issues
1. My device does not appear in the upload box in Axium Design Portal.
There a number of possible reasons for this:
The discovery mechanism uses broadcast over the local network, so ensure that the
mobile device and PC are both accessible within the same subnet. Routers do not
pass broadcast traffic over WAN ports.
If the PC is connected to multiple networks, ensure that each is on a unique subnet.
Ensure that Update Mode is enabled in the settings on the mobile app.
Ensure that only one instance of Axium Design Portal has the upload box open at a
time.
If all else fails try terminating the mobile app, toggling Wi-Fi, or rebooting the device. Some
wireless access points are not particularly compatible with Apple devices. Try a firmware
update for the AP or swap it out with a new one.
2. Sending commands to an Axium Controller or Amplifier doesn’t work and a
message displaying “Unknown Object” appears.
This error message is a response from the Axium Controller or Amplifier signifying that the
command it received does not exist.
The most common reason for this is that the Axium Controller or Amplifier has not been
uploaded to after the command was referenced. Whenever changes are made requiring
another upload, the device in the project viewer will become highlighted.
Another possibility for this message is the presence of a duplicated device on the network
creating conflict. This can accidentally be done by uploading the same device configuration
to more than one Axium Controller or Amplifier.
It is important to note that when commands are added to an Axium Controller or Amplifier,
they are only uploaded to the device when something in the project uses them. There is a
common misconception that because the commands were added and an upload was
performed, that the device is set up. Whenever a command is referenced for the first time,
it will require another upload in order for that command to actually be present on the Axium
device.
3. Occasionally when using my iOS device, commands sent to an Axium
Controller or Amplifier no longer work.
There is a bug prior to iOS 7 which causes the multicast DNS resolution to stop working. The
Axium protocol uses this technology in order to identify devices on the network. Whenever
this bug is triggered, the mobile device is unable to determine the IP address of the Axium
Controller or Amplifier resulting in no communication between the devices.
28
When this problem occurs, toggling the Airplane Mode switch in Settings restores the Apple
DNS service to a functional state.
A permanent workaround is to set static IP addresses for the Axium Controllers and
Amplifiers so that the DNS service is not required.
4. My iOS device does not connect or takes a very long time to connect to an
Axium Controller or Amplifier.
Unfortunately some wireless access points -especially very old ones, do not handle multicast
traffic well. In the event that one of these bad access points is in use, standard Apple
discovery mechanisms will fail also. The best solution is to upgrade to a decent access point,
but setting static IP addresses for all Axium hardware will also workaround this issue.
5. 2-Way Feedback to my iOS device is unreliable.
Again, an issue with many wireless access points. Apple seems to be very selective on the
format of ARP requests that it receives. ARP is a low level protocol which is essential for
communicating on networks. Unfortunately a few access points are incompatible with
Apple’s expected format of request, so although other devices respond to these ARP
requests properly, Apple devices will not. The first option is to try upgrading the firmware of
the wireless access point. Many manufacturers will have become aware of this ARP issue
since the proliferation of Apple mobile devices in recent years, and will have fixed these ARP
issues. If a firmware update does not help or is not available, then you will need to use a
different access point.
6. The layout does not fit the iPhone 6/6+ screen properly
These new iPhones have a feature called ‘Display Zooming’. What this feature does in fact is
lower the screen resolution resulting in a larger image. This results in two issues:
i) The screen size selection in ADP is misleading and doesn’t work as expected ii) The user changes the ‘Zoom’ preference and the previously working layout is not sized
correctly anymore. The first issue is solved when educated by this new feature. When ‘Zooming’ is active the
target design size must change to suit. For iPhone 6 this is 1136x640 - the same as the
iPhone 5 size. With the iPhone 6+ however the size is changed to 2001x1125.
The second issue can be solved by uploading a duplicate layout for both possible screen
sizes. The app will automatically select the appropriate layout based on the users ‘Zoom’
preference.
29
Tutorials
This section will go over in specific details certain functionalities and tasks that people often struggle
to comprehend when using Axium Design Portal for the first time. The tutorials assume at least a
basic understanding of using Axium Design Portal to create mobile app designs. They begin at the
stage after adding a new mobile app design into the project, or adding a template from the
Templates Hires gallery and performing any necessary adjustments to suit.
TODO: Scheduled Event Applet, Apple TV applet,
Integrating an applet
In this tutorial we will add the Axium
Media Player applet. For a completed
example see the Media page in any of the
templates or the Applet Examples Hires
gallery.
First add a new instance of the Axium
Media Player applet to the page. This is
done by right clicking the page and
choosing from the entries in the Add new
applet submenu. Now the applet requires
configuration to integrate functionally as
well as aesthetically. Customize the
applet properties by right clicking the
applet and selecting the Properties menu
entry.
Properties of pertinence are:
Zone
Media Player
ShowProgress Bar/Text
Show Album Art
View Type
The Zone property indicates what Axium amplifier zone the applet will control. The (page) entry will
cause the applet to use the zone that the page uses.
The Media Player property indicates which Media source the applet will control. Note that in order
for the applet to function correctly, the currently selected source of the applet zone must match this
property.
Figure 33 – New Axium Media Player applet
30
The ShowProgress Bar/Text property check
boxes indicate how the track duration will be
presented when the playback information is
being displayed.
The Show Album Art property check box
indicates whether or not album art will be
shown in the bottom right corner when the
playback information is being displayed.
The View Type property offers 4 different
options:
Integrated
Content Browser
Now Playing
Empty Frame
The Integrated view type is the default choice
and is used to display both the navigation and
playback functionalities within one frame.
When a track or stream is playing the applet
view will change to the playback mode.
Because this view type encapsulates the
functions of the Content Browser and Now
Playing view types, it must be exclusive to
those modes. This means on a single page this
view type should never be used with either of
those two or else the behaviour is undefined.
The Content Browser view type will only present the navigation functionalities.
The Now Playing view type will only present the playback functionalities.
The Empty Frame view type will not display anything. It is only really useful for the purpose of
applet persistence.
Figure 34 – Axium Media Player applet properties
31
Figure 35 – Setting button class
Now the applet itself is configured. Next we need to link buttons to the various functionalities that
the applet provides. To create these associations, either right click the button and choose from the
Class menu or use the Class selection box in the button properties area. Available applet actions are
listed under the Applet submenu, and then under the appropriate specific submenu thereafter as
per the applet type being integrated. Map these applet functions to buttons and label them
appropriately.
In finishing, implement any page navigation to access the applet. Be sure to give whatever button
that triggers this navigation a button class to change the applet zone source to the corresponding
media player that the applet is configured with.
There is a wide assortment of applets available each with differing requirements and caveats. Check
the corresponding section in this document for details on implementing a particular applet.
32
Figure 36 – Script editor
Integrating a script
In this tutorial we will integrate the Denon / Marantz control script. For a complete example see the
script example projects.
Firstly you need to setup the controller with the script. Depending on your current project state,
one of the following 3 options may be more appealing:
Use the controller from the example project with the script
Copy/Paste the script object from the example controller into your own existing controller.
Be sure to hold the CTRL key when pasting or dragging so that a deep copy is performed.
Copy/Paste the contents of the script into a new script on your existing controller. Ensure
that the objects are all mapped according to the script definitions. This involves manually
creating and configuring the variables included in the example project.
The controller configuration should now look something like this:
33
Figures 37-40 – Linking page items with variables
The next step is to prepare the mobile app design for the script integration. In this case we are using
the Cosmos template and removing the existing programming for all the buttons on the homepage.
The buttons in the lower panel are now ready for linking with the appropriate variables. Set the up
and down arrow buttons to the Increment and Decrement button classes respectively.
Some basic control of the AV receiver should now be possible by this step. Next we are adding
source control which requires a bit more thought to do. First go to line 33 in the script and note the
numbers of the sources that you want to integrate. Since we know the Source variables handle 10
sources each, it is easy to determine which variable to link in order to implement control for a
particular source number. Create links to the available buttons on the mobile app design with the
appropriate source variables. Then set the button class to one of the single digit (0..9) Axium
Variable classes, and the buttons will then be able to control that source.
34
Figure 41 – Setting the button class
TODO:
Howto: for making modifications to the script to use different source / surround modes. The various
Denon and Marantz models each support different source and surround combinations so some
tweaking in order to access the special features may be required.