UD Mobile

From Universal Devices, Inc. Wiki
Jump to navigation Jump to search

Installation

Download on the App Store Get it on Google Play Available at Amazon Appstore

Notes

UD Mobile works with firmware 5.0.16 and greater. Firmware versions lower than 5.0.16 may work but not officially supported and have known issues which are only fixed by firmware update. The latest 5.x firmware now requires a 500 series Z-Wave board. If upgrading from 4.x to 5.x be sure to select firmware which is compatible with your system. Some information contained on this page may be specific to iOS or Android.

At this time (January 2022) UD Mobile does not yet have Geofence capability. It is in development, but no timeline known for when it will be implemented and available for testing or release.

Quick Start Guides

Existing Portal Users

Upon Installation the app will prompt to setup using ISY Portal. Select Yes.

The app will prompt for ISY Portal login. Select Yes. If app prompts for Portal credentials enter your credentials and save. App may also show a dialog with existing Portal accounts. If this is initial installation select Add New Portal Account.

App will then show a list of ISYs on your portal account or a list of ISY Portal accounts. If a list of Portal Accounts is presented select the Portal account which contains the desired ISY. Select the desired ISY.

Select SAVE at the top right. Then select YES when prompted to synchronize. Wait for synchronization to complete. After synchronization the app will be ready to use on remote connections.


Adding Another ISY (Existing Portal Users)

These instructions assume the ISY is already linked to ISY Portal.

Select Settings-Tab > Systems > Add (top right).

The app will prompt for ISY Portal login. Select Yes. If the ISY is using the same Portal Account as your previously linked ISY(s) select the existing Portal Account from the list. If the ISY is using a different Portal account select Add New Portal Account.

After Portal Account has been selected the app will show a list of available ISYs. Select the desired ISY to add to the app.

Select SAVE at the top right. Then select YES when prompted to synchronize. Wait for synchronization to complete. After synchronization the app will be ready to use on remote connections.

Remote Connections

Remote connection on UD Mobile can be achieved in 3 scenarios.

First is our managed method using ISY Portal. ISY Portal has competitive prices of $23 for the first 2 years and renewals cost of $20 for two years (prices current as of 06/2021). If your ISY has not been associated with the ISY Portal in the past we offer a 30 day free trial. ISY Portal Installation instructions can be found here https://wiki.universal-devices.com/index.php?title=ISY_Portal_Installation_Instructions

Second is an unmanaged direct connection. The unmanaged method requires a Trusted CA Signed SSL Certificate. The Trusted SSL CERT is required for reasons stated below in App Transport Security. Instructions on adding a CERT to your ISY can be found here: https://www.universal-devices.com/docs/production/ISY994%20Series%20Network%20Security%20Guide.pdf . There are methods to add a Self Signed CERT to the Trusted Key Store on Android, however it is beyond the scope of our support and may require root on some devices.

Finally a local connection can be established on a remote network if running a VPN Server on the same local network as the ISY. To use this method select "Only use Local Connection" in the local connection settings. Setting this option will instruct the App to ignore remote connection settings and only use the local network.

App Transport Security (ATS) iOS

App Transport Security (ATS) is disabled by iOS for local loads (1), for this reason Local Connections do not need a Trusted CERT, ATS requires a Trusted CERT for Remote Connections. While it is possible for the apps to disable ATS it would make all connections less secure and we would have to meet the exception requirements (2) during app review which we likely do not meet.

(1) https://developer.apple.com/documentation/bundleresources/information_property_list/nsapptransportsecurity/nsallowslocalnetworking " ATS doesn’t block local loads by default in newer versions of the OS"

(2) https://developer.apple.com/documentation/security/preventing_insecure_network_connections#3138036

"The app must connect to a server managed by another entity that doesn’t support secure connections." Portals provided by UDI and Third parties support secure connections, and UDI controls the firmware. So, this does not apply. Apple has also mentioned this will be removed in the future.

"The app must support connecting to devices that cannot be upgraded to use secure connections, and that must be accessed using public host names.". ISY firmware does support secure connections, so this exception does not apply.


Local Connections and Local VPN

Local connection on UD Mobile can be achieved in 2 scenarios. Credentials for local connections are under Advanced-Settings in the Systems Screen.

First is using a local connection along with a remote connection. This will require that "Only use Local Connection" setting is switched off, then add your local WiFi network(s) in System Network Relations. Linking a WiFi Network will instruct UD Mobile to use the Local Connection Settings when your device is connected to a linked network.

Second is only using the app on the local network (or VPN). This will require that "Only use Local Connection" setting is switched on. The app will now only connect using the Local Connection Settings, this is intended for users who have a local VPN or users who do not setup a remote connection.

Note that the Local IP Address must be fully qualified starting with "http://", also be sure there is no "/" at the end of the address.

Migration

If migrating your current ISY setup to a new ISY/Polisy all that is needed is a change of Remote and Local URLs. First backup UD Mobile in case of errors this way Favorites and User Preferences will not be lost. Local Connection change involves changing the Local IP Address, Port, Username, and Password. Portal URL change would involve hitting the delete button in the Systems Portal window, then selecting the Add button, then select your Portal Account, then select the replacement system from the list of ISY connected to ISY Portal. Only nodes with the same Node Address will remain on UD Mobile after migration. If not migrating from a backup or if nodes are manually linked with a new Node Address, then Favorites will be removed on synchronization. Some versions of UD Mobile will prevent synchronization if UUID (the unique id of the system hardware) does not match, the UUID can be cleared at the bottom of Advanced Settings.

Backup and Restore

Backing up the UD Mobile App will save all App Systems, Favorites, and Customizations.

Restore

iOS Restore

iOS will allow backup to local storage and iCloud, however will only allow restore from a local backup. If your iOS backup was saved to iCloud, go to Apple's Files App then go to iCloud, locate the UD Mobile backup, then long press and select Copy (or Move), then back out to the "Browse" screen and select "On My Phone", then paste the backup file into your iPhone local storage, the backup should now be available for restoration.

See "All Platforms" below for more information.

Android Restore

Android (Only Google's variant tested) will allow backup and restore from local storage and cloud providers such as Google Drive. Android cloud providers can be accessed by clicking the menu in the System File picker, the System file picker should show registered cloud providers.

See "All Platforms" below for more information.

All Platforms

If restoring over a configured app setup go to Settings-Tab > Backup. If restoring to a new device or new installation select cancel when prompted to add Portal Account, enter a temporary System Name, then select Save. When UD Mobile prompts for synchronization select Cancel. Note that errors may be presented as the there are no links to systems. Now go to Settings-Tab > Backup, then select Restore.

Local, Remote, and Portal passwords may need to be reset after import, passwords may persist if backup is imported on the same device but is dependent on the device secure key store. If having trouble with Remote Portal connections please logout all ISY Portal Accounts (Settings-Tab > ISY Portals Accounts) then re-enter the Portal Account in for each System (Settings-Tab > Systems). Currently iOS and Android backups are not compatible with the other platform. Amazon Android and Google Android backups are compatible with each other.

Backup

Backing up the UD Mobile App will save all App Systems, Favorites, and Customizations. Backups can be saved from Settings-Tab > Backup. See platform specific backup instructions below.

iOS Backup

iOS will allow backup to both local storage and iCloud (See "Restore: above for iCloud backup restorations). After selecting "Backup" navigate to the desired directory then select "Move" on the top right of the screen.

Android Backup

Android (Only Google's variant tested) will allow backup to local storage and cloud providers (i.e. Google Drive). Android cloud providers can be accessed by clicking the menu in the System File picker, the System file picker should show registered cloud providers.

Home Tab

The initial home tab screen will show a list of the users ISYs. Clicking an ISY will show the “Devices and Scenes”, “Network Resources, “Variables” and “My Programs” folders.

Clicking on a folders will show the folder contents, clicking on a node will show the Node’s Dashboard (see Node Dashboard). There may be additional options which are selectable on the right side of a Node list item, see the Node Type below for descriptions and actions. Some Node Types have an Action Indicator displayed at the top left of a Node’s icon (left side), see the Node Type below for descriptions and actions.

All nodes including ISYs and folders can be show/hidden by clicking the edit icon (pencil) at the top of the screen then clicking the add/remove icon to the left of the list item. Note that some Node Types have additional edit functions, see the Node Type below for edit functionality.


Devices and Scenes

Clicking on the “Devices and Scenes” folder will show the user the file structure as shown in the Admin Console (AC). The file structure can be change by the user from UD Mobile or the AC. If changes to file structure are made from the Admin Console, then users will have to synchronize UD Mobile from the “Devices and Scenes” folder by pressing the synchronize icon at the top right of the screen.

Edit a Node by clicking the edit icon then clicking the node in the list. The Edit dialog will be presented with edit options if they exist. Currently not all options are available from UD Mobile, please use the Admin Console for access to all available edits.

Grouped Nodes can be shown by clicking the expand icon on the right side for a node item. The expand icon will only be presented for nodes which have grouped children. If a node has grouped children but all child nodes have been hidden, the user must unhide the child nodes by clicking the edit icon to view children.

The Node Toggle Indicator (Action Indicator) is a filled or empty circle at the top left of the Node’s icon. The Toggle Indicator will only show for nodes which accept on/off (DON/DOF) commands. If UD Mobile has NOT received status for the node from the ISY then the Toggle Indicator will not be show until the node’s status is received. Node status is needed to determine if an on or off command should be sent. If UD Mobile does not have the node’s status clicking on the node’s icon will open the Node’s Dashboard (see Node Dashboard).

Clicking on a Node will show the Node’s Dashboard (see Node Dashboard).


Network Resources

Clicking the “Network Resources” folder will show an alphabetical list of Network Resources. Clicking on a Network Resource will show the Network Resources’ Dashboard (see Node Dashboard).

Clicking on the Network Resources’ icon (left side) will execute the Network Resource. An Action Indicator is shown next to the Network Resources’ icon to indicate it is actionable.

Network Resource Edits are currently not available from UD Mobile, please use the Admin Console then synchronize UD Mobile with ISY.


Variables

Clicking the “Variables” folder will show the “Integer Variables” and “State Variables” folders. Clicking on either variable-type folder will show an alphabetical list of the variable-type. Clicking on a variable will show the Variable’s Dashboard (see Node Dashboard)

Variable Edits are currently not available from UD Mobile, please use the Admin Console then synchronize UD Mobile with ISY.


Programs (My Programs)

Program folders contain a menu (3 dots) on the right side of the list item. Clicking the Program Folder menu will open the Program Folder’s dashboard which shows folder status (see Node Dashboard).

Clicking the “My Programs” folder will show the user the Program file structure as shown in the Admin Console (AC). Currently the file structure must be changed in the AC then synchronized to UD Mobile by clicking the synchronize icon at the top right of the screen.

The Program Toggle Indicator (Action Indicator) is a filled or empty circle at the top left of the Program’s icon. The Toggle Indicator will show if the program is running or stopped, clicking the Program’s icon will toggle this action. The Toggle Indicator will only show if UD Mobile has the Program’s status. UD Mobile does not request Program status on app launch by default. To request Program status on app launch, go to Settings-Tab > Systems > Your-System-Name > Advanced-Settings > Program-and-Variable-Settings then toggle Request-Status-of-all-Programs. Please see Favorite Examples for custom program toggle (i.e. run if/else)

Program Edits are currently not available from UD Mobile, please use the Admin Console then synchronize UD Mobile with ISY


Favorites

Add New Favorite

Add

Go to the Favorites Tab. Select add ("+") at the top of the screen. This will open the Favorites Editor Screen.

Custom Name (optional)

Adding a Custom Name will override the Display Node name if available.

Type

Favorites Type allows the user to choose click actions for a favorite item.

  • Node Type will display an ISY Node and requires the user to select a Display Node (below). Favorites of Type Node have 2 Interaction Types; Toggle and Open-Dashboard. Interaction Types can not be defined by the user. See Toggle Indicators below. For custom toggle please use Command Type along with an ISY Program which has your toggle preferences in the IF section, then select IF as the command (program may need to be disabled in ISY to prevent IF trigger).
  • Folder Type will act as a folder allowing the user to add additional favorites inside. Favorites of Type folder also allow for an optional display node which inherits toggle ability from Node Type (above).
  • Command. This Type will allows users to specify any number of Node Commands. Pressing a Favorite of Type Command will execute the defined commands. Favorites of Type Command also allow from an optional Display Node, the display node does not inherit toggle ability. The Display Node does not have to match Command Nodes. See Commands below.
  • Status. Favorites of Type Status do not have clickable actions.
  • Empty. Favorites of Type Empty will create an invisible tile. Empty tiles will be shown in Edit Mode for editability.

Icon

Optional Icon. If not set default will be used. If the Display Node (below) is set an the Display Status (below) has an Individual Status Mappings (see Individual Status Mappings) the Favorites Icon has lower priority to Individual Status Mappings with icons.

Color

Optional Icon Color (Currently Android only). If the Display Node (below) is set and the Display Status (below) has an Individual Status Mappings (see Individual Status Mappings) the Favorites Color has lower priority to Individual Status Mappings with color values. Hex color is 6 character hex prefixed by "#" (i.e. #808080). Eight character hex codes may be accepted with the first 2 characters representing alpha. Alpha color may show the original icon color under the user input color.

Display Node

The node which will be displayed. During Display Node selection an expand (downward chevron) icon next to a node indicates that the node has grouped children (grouped nodes), to see the children press the expand Icon. The Display Node can be cleared by pressing the delete (trash icon) during Display Node selection.

Display Status

After a node has been selected the Display Status will be shown (i.e. Status, On-Level, Ramp-Rate, ect.). This will allow users to change the default display status.

Node Toggle Indicator

The Node toggle indicator will only show for Favorites which have (#1) "Status" selected as the Display Status, and (#2) the selected node must accept on/off commands. Also (#3) if the App has NOT received a status for the node from the ISY the toggle indicator will not be show until the node's status has been received. Node status is needed to determine if an on or off command should be sent to the node. If the App has NOT received a status for the node, clicking the Favorite item will open the Node's Dashboard which shows all status values and controls for the selected node.

Program Toggle Indicator

The Program toggle indicator will only show for Favorites which have (#1) "Status" selected as the Display Status. Also (#2) if the App has NOT received a status for the program from the ISY the toggle indicator will not be show until the program's status has been received. Program status is needed to determine if the Run or Stop command should be sent to the program. If the App has NOT received a status for the program, clicking the Favorite item will open the Program's (Node's) Dashboard which shows all status values and controls for the selected program. To receive program status values on App startup go to Settings-Tab > Systems > Your-System-Name > Advanced-Settings > Program-and-Variable-Settings then toggle Request-Status-of-all-Programs.

Commands

This will be shown if Command is selected as the Favorite Type. To add a command select the add (plus) icon next the the Commands header. Note that to preserve database integrity, the app will prompt to save for new favorites, if the app does not automatically open the Command Selection dialog press the add icon again. Select a node (similar to Display Node above). After a node has been selected the command dialog will show a list of available commands. Note that a menu (three dots) next to a command indicate that the command supports no-parameter and parameter execution (i.e. ON or ON-to-50%). If a command requires parameters or if the parameter option (menu) was selected the Parameters dialog will be show. After entering any parameter adjustments select save. Currently commands support deletion not editing.

Save Favorite

Select Save at the top of the screen.

Edit Favorite

Go to the Favorites Tab. Select Edit (pencil icon) at the top of screen, then click the Favorite item for Edit Options. When edits are finished click the edit (pencil icon) at the top to finish editing.

Delete Favorite

Go to the Favorites Tab. Select edit (pencil icon) at the top of the screen. Click the Favorite item. Select "Delete".

Move Favorite

Go to the Favorites Tab. Select edit (pencil icon) at the top of the screen. Click Move or Move-to-Folder. For Move-To-Folder select Paste when in the desired directory, the first screen is the home directory. To move position in the current directory long press the favorite item then drag to position.

Customizations

Mapped Colors

Icon Colors can be changed at the Global, Individual, and Favorites levels. Global and Individual Color mappings can be set to match node status values. Hex color is 6 character hex prefixed by "#" (i.e. #808080). Eight character hex codes may be accepted with the first 2 characters representing alpha. Alpha color may show the original icon color under the user input color. For installers setting colors for users please follow WCAG Guidelines. Generate WCAG colors at http://colorsafe.co/ with a off white (#fffdff) background.

Favorites Colors

Change favorite colors by clicking edit at the top of the favorites screen then click the desired node and select Edit. Favorites Colors have the lowest color priority and is intended for favorites folders which will not have a status value.

Global Colors

Change global colors based on node values (Null/Zero/Positive) from Settings-Tab > Global-User-Preferences. Global Mapped Colors have a lower priority than Individual Mapped Colors and have a higher priority to Favorites Mapped Colors.

Individual Colors

Change Individual Colors from the home/favorites screen by clicking the edit button at the top, then click the desired node, then click Configure Colors/Values/Icons. Select Add at the top of the Mapped Values screen to create a new mapped value. Mapped Values have the highest priority of all mapped colors (Global/Favorites). See Individual Status Mappings for details.

Individual Status Mappings

Change Individual Status Mappings from the Home/Favorites screen. Click the edit button, then click the desired node, then click Configure Colors/Values/Icons.

Individual Status Mappings can change a node icon, color, value, value-prefix, and value suffix based on the status value.

Comparison

Value comparisons include Null, Equal-to, Greater-than-or-equal-to, Less-than-or-equal-to, and Not-Equal-to. The app will only return one mapped value even if multiple mappings overlap. Value mappings are evaluated in the following order with the first matched being returned. Value Mapping order: Equal, Greater-than-or-equal-to (descending value order; highest comparison value will be matched), Less-than-or-equal-to (ascending value order; lowest comparison value will be matched), Null, Not-Equal-To (descending value order; highest comparison value will be matched).

Icon

(optional) If not set the default will be used. If set this will override Favorite icons.

Icon Color

(optional) hex color code. This will change color for both defined and default icons. This has the highest priority of all color settings (Global/Favorites)

Formatted Value

(optional) Sets a name for a status value. i.e. if value equals 0 (0%) show as the word OFF.

Prefix

(optional) Set a prefix in front of a value. i.e. put $ in front of a variable value.

Suffix

(optional) Set a suffix behind a value. i.e. put % behind a variable which is used to track lights or the degrees sign behind a variable used to track temperature.

Edit Locks

Lock all top bar action items, Admin Tab Items and Settings Tab Items. Only the Global User Preferences item will be active on the Settings Tab and only the Lock Edits available to change with password.

Lock

To lock settings go to Setting Tab > Global User Preferences. Add a pin in Edit Lock Pin (Note: this is NOT an encrypted pin and will persist backup/restore), then click Lock Edit and set to true.

Unlock

To Unlock settings go to Setting Tab > Global User Preferences then click Lock Edit, enter pin, then set to false.

Favorite Examples

Favorite Custom Toggle

The following is an example of adding a custom toggle for a door lock, but the process is similar for all nodes/programs/variables. A door lock is used in this example as it does not support On or Off commands, so the app will not show a toggle indicator and will only open to the Node's Dashboard when clicked on the Favorites Screen.

First we must create a Program in the Admin Console (Program creation not yet available from UD Mobile). See Program Notes in program image. The program must be disabled to prevent unintended behavior.

CustomToggleProgram.png

In UD Mobile create a new favorite. Change the Type to Command, and set the Door Lock as the Display Node. Add The program created above as a Command Node and select "Run If" as the Command. Note this Favorite was given the Custom Name "Back Door" which will override the original Node Name.

FavCommand.png

We now have a Favorite item which can toggle the "Back Door" lock. Also because we have a Display Node there is a menu (three dots) which will open the Node's Dashboard, which can be great if the lock is jammed and we must use the unlock control as the toggle will always try to lock in the program created above.


FavTabCommand.png

Node Dashboard

Show/Hide Status and Commands

From the Node's Dashboard click the edit icon (pencil on top). Now press the add/hide (+/-) buttons to the left of the status or button.

NodeDashboardEdit.png


Move Status and Commands

From the Node's Dashboard click the edit icon (pencil on top). Now long press the move icon (three lines) on the left side of the status or button. Note that status and buttons are grouped and can only be moved within the same group.





Admin Tab

Polyglot Cloud

Access Polyglot Cloud (PGC) from the Admin Tab of UD Mobile by clicking the "Polyglot Cloud" list item.

If UD Mobile has more than one ISY Portal linked the user will be presented with a dialog to pick the desired ISY Portal.

If the users ISY Portal Account has more than one ISY the user will be presented with a dialog to pick the desired ISY.

The Polyglot Cloud (PGC) Screen will show a list of installed Node Servers. Only Cloud Node Servers can be edited on the PGC Screen.


Add PGC Node Server

Add a new Node Server from the Polyglot Cloud Store. The PGC Store can be accessed from the Polyglot Cloud Screen by clicking the add (plus) icon at the top right.

Clicking on a Node Server in the PGC Store will take the user to the Node Server’s Store Dashboard. Add the Node Server by clicking “install” at the bottom of the screen. Note that a Node Server must be removed from the Node Servers Dashboard page (see Edit a PGC Node Server). Once the Node Server is added the user may need to add or edit parameters and start the Node Server. Parameter Edits and Start/Stop functions can be found on the Node Servers Dashboard Page. When starting a PGC Node Server please allow a few minutes for the Node Server to initialize after pressing the start button.


Edit PGC Node Server

Status indicators for PGC Node Servers will show Red for Stopped, Green for Started, and Yellow if Started with Notices.

Edit a PGC Node Server by clicking the Node Server in the list. This will present the Node Server Dashboard which has Start, Stop, Update and Delete Functions.

Clicking on Configuration will take the user to the Node Server Configuration Screen. The Configuration Screen allows users to add, edit, or remove parameters.

Edit a parameter by clicking the parameter in the list, then update the value, then press save.

Remove a parameter by clicking the parameter in the list then clicking the delete icon (trash) at the top right of the Edit Parameter dialog.

Add a parameter by clicking the “Add Parameter” button at the bottom of Custom Configurations list on iOS or by clicking the add button at the top right of the screen on Android.


Alexa

Add or edit your Alexa Spoken configuration from Admin Tab > Alexa or from the Node Dashboard by clicking the voice icon at the top of the screen.

Settings Tab

Systems

Clicking Systems on the Settings Tab will show all linked ISY/Polisy Systems

Edit/Add System

Clicking on a System in the Systems List will open the System Edit Screen for the selected ISY/Polisy. Clicking on the add "+" icon on the top right will open the Add System screen.

System Name

Required System name. System Name must be unique from any other system names in the App. System Name is populated automatically if your ISY is selected from ISY Portal, but must be entered manually if not using ISY Portal. System name will show as a list item on the Home Tab. Changing System Name requires synchronization to change the Home Tab list item name.

Remote Connection Settings

See Quick Start Guides above.

Local Connection Settings

See Quick Start Guides above.

Program And Variable Settings

Enabling any item in the section will request status for the selection when the app is started. Requesting the status of all Programs and/or Variable may cause a longer delay in status population when opening the app.

System Status

Disabling this setting will instruct UD Mobile to not start a subscription with the ISY, so no status values will be requested when the app is opened. This is intended for developers with multiple Systems and the user would like to disable the System when not testing.

Global Settings

Currently Android Only. Global Subscription Duration affects all systems for UD Mobile. This sets the duration in minutes of the subscription to your ISYs. The app will not close the subscription until the Subscription Duration time has passed or when the operating system requests resource, whichever comes first. Setting this number to \"0\" will close the subscription as soon as UD Mobile is paused and the subscription will have to be reestablished to get node status values. Setting this to a negative number will leave the subscription open until the operating system is low on resources. Please note that the longer the subscription duration the more data and battery consumed by UD Mobile, a shorter duration may cause longer delays for status values when the app loses focus. While the subscription is active UD Mobile will show a notification and may show an app icon badge. Android requires developers to notify users with a notification when an app is using resources in the background, most android devices will allow users to ignore notifications based on type.




Errors

Note: Node Server developers should check Node Server functionality with UD Mobile prior to release. UD Mobile has error checking which may be different than the Admin Console. Below are a few common errors and error messages.


Node Status Relation Cursor is empty

This is usually related to a NodeDef Accepts Param init value set to a Status value that does not exist

Example: init="GVP". GVP is not a defined Status ID. 

<nodeDefs>
  <nodeDef id="controller" nodeType="139" nls="ctl">
    <editors />
    <sts>
      <st id="ST" editor="bool" />
    </sts>
    <cmds>
      <sends />
      <accepts>
        <cmd id="DISCOVER" />
        <cmd id="REMOVE_NOTICES_ALL" />
        <cmd id="UPDATE_PROFILE" />
	<cmd id="DEBUG">
	  <p id="" editor="DEBUG" init="GVP"/>
	</cmd>
      </accepts>
    </cmds>
  </nodeDef>
Retrieved from "https://wiki.universal-devices.com/index.php?title=UD_Mobile&oldid=8963"