KMC Converge GFX User's Guide

KMC Converge GFXUser Guide

KMC Controls, 19476 Industrial Drive, New Paris, IN 46553 / 877-444-5622 / Fax: 574-831-5252 / www.kmccontrols.com

GENERAL INFORMATION ....................................................................2Support .....................................................................................2Notes and Cautions .....................................................................2Important Notices .......................................................................2

INSTALLING KMC CONVERGE GFX .......................................................3Installing ...................................................................................3Licensing ...................................................................................3Browser support .........................................................................3

USING CONVERGE GFX ......................................................................4Introduction ...............................................................................4Quick Start Guide ........................................................................4Setting up the KMCConvergeGFXService.........................................5Mobile Apps ...............................................................................6User setup .................................................................................7Confi guring Graphics ...................................................................7

Items ...................................................................................7Templates ..................................................................... 15

Generating Graphics .................................................................. 16KMC Automatic Site Build ................................................ 16Generate Site / Generate Page .......................................... 16

Customizing the CSS Template ................................................ 17Properties .......................................................................... 17Import / Export ................................................................... 18

2 KMC Converge GFX User Guide Revision A

Notes and CautionsNOTE: In this document, a NOTE provides additional information that is

important.

CAUTION In this document, a CAUTION indicates potential personal injury or In this document, a CAUTION indicates potential personal injury or equipment or property damage if instructions are not followed.equipment or property damage if instructions are not followed.

Important NoticesKMC Controls® and NetSensor® are all registered trademarks of KMC Controls. KMC Conquest™, KMC Commander™, KMC CommanderBX™, KMC Connect™, KMC Connect Lite™, KMC Converge™, and TotalControl™ are all trademarks of KMC Controls. All other products or name brands mentioned are trademarks of their respective companies or organizations.

All rights reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in any form by any means without the written permission of KMC Controls, Inc.

The material in this document is for information purposes only. The contents and the product it describes are subject to change without notice. KMC Controls, Inc. makes no representations or warranties with respect to this document. In no event shall KMC Controls, Inc. be liable for any damages, direct or incidental, arising out of or related to the use of this document.

Specifi cations and design are subject to change without notice.

GENERAL INFORMATIONSupportAdditional resources for installation, confi guration, application, operation, programming, upgrading and much more are available on the web at www.kmccontrols.com. To see all available fi les, log-in to the KMC Partners site.

KMC Converge GFX User Guide Revision A 3

INSTALLING KMC CONVERGE GFX

InstallingThe KMC Converge GFX module installs at the same time that KMC Converge is installed. No additional fi les are needed.

For third party versions of Niagara, the fi le kmcConvergeGFX.jar must be in the modules folder.

For complete installation procedures, see The KMC Converge User Guide.

LicensingKMC Converge GFX is a licensed option of KMC Converge. If this option was not included with the original license and certifi cate fi les Cse.certifi cate and Cse.license, you will need new fi les. See The KMC Converge User Guide for the instructions.

Browser supportKMC Converge GFX works with HTML5 compliant browsers and has been tested for use with the latest versions of the following browsers.

• Google Chrome• Mozilla Firefox• Microsoft Internet Explorer 11• Google Chrome for Android/iOS• Safari for iOS• Safari for OSX


In troductionThe KMC Converge GFX service is a tool used to confi gure and generate responsive, HTML graphics for KMC Converge AX or any other open brand of the Niagara AX Framework. The service allows you to easily confi gure your graphics using familiar Niagara AX properties, and the responsive graphics can be viewed on any device with any size screen and still look great.

Quick Start GuideKMC Converge GFX allows you to automatically generate graphics for any compatible KMC Bacnet Devices in your KMC Converge AX station. Follow these steps to quickly setup KMC Converge GFX and view automatically generated graphics:1. Add the KMCConvergeGFXService to the Services section of your running

AX station from the kmcConvergeGfx palette. 2. Add all of the Mobile Apps (Mobile Alarm Console App, Mobile History App,

Mobile Property Sheet App, Mobile Px App, and Mobile Schedule App) into your “Apps” section, which is found directly under the Config of your station.

3. Go to the Property Sheet of the KMCConvergeGFXService and set the Title of your site, and point the Current Time Ord to a CurrentTime component in your station (you can find this in the kitControl palette, under the Timer folder).

4. Go to the K M C Service View of the KMCConvergeGFXService, and click on the Build Site button. Your graphics should be automatically configured in the service.

5. Click the Generate Site button to create HTML files based on your config-ured graphics. You can find them in the Files section of your station, in a folder named after the Title of your site.

6. Add a kmcGuest user from the kmcConvergeGfx palette to the UserService of your station (found under “Services”). Change the username and pass-word as desired, and set the Nav File and Mobile Nav File properties to the .nav file found in the folder for your Site that was generated in the previous step.

7. Log in to your new user from a web browser on any device.

USING CONVERGE GFX


Setting up the KMCConvergeGFXServiceThe fi rst step in setting up KMC Converge GFX is to add the KMCConvergeGFXService to your running station:1. Open the kmcConvergeGfx palette in KMC Converge AX.2. Drag the KMCConvergeGFXService from the palette and to your running

station’s Services section under the Config.After adding the KMCConvergeGFXService to your station, there are a number of properties in its Property Sheet to be setup.

Title: The name of your site to be displayed on the home page of your graphics.

Icon: An icon to be displayed beside your Title, which is also used as a navigation button to get back to the home page of your graphics. Hit the icon to view a selection of pre-made icons from Font Awesome.

Custom Icon: You can also specify your own image to use as an icon. If set, this property will override the Icon property. Icons are scaled proportionally to fi ll the space used by icons. If you’d like for your custom icon to be smaller, consider adding space around it in an image editor of your choice.

Custom Header H T M L: This is an advanced feature for inputting your own web code (HTML/CSS/Javascript) to use as a replacement site header. If enabled, anything in this fi eld will be used in place of the entire existing, default header.

Custom Header H T M L Enable: Enables the custom header. If left false, the Custom Header H T M L will never be used in place of the default header.

Hide Header: Hide the default header entirely and only show the navigation bar.

Head H T M L: This is an advanced feature inserting your own web code (HTML/CSS/Javascript) into the HTML <head> section of your KMC Converge GFX pages. This can be used to include custom CSS templates or Javascript libraries across your entire site.

Footer H T M L: This is what is displayed at the bottom of every one of your KMC Converge GFX pages. By default, it is setup to show a hyperlink to an external website, and include a logout link for users. You can edit the hyperlink by changing the default “<a href” value from “http://www.kmccontrols.com” to something else. You can also empty this property to not show any footer.

Current Time Ord: This ord is used to show the current time and date in your header. To add in a CurrentTime object to your station to use with this property, open the kitControl palette, expand the Timer folder, and drag a CurrentTime object into your station.

Css Template: See the topic Customizing the CSS Template on page 17 for information on the CSS Template.

License Mode: Will either say “Registered” or “Unregistered.” If you have obtained the proper licenses, double check them by opening a Platform connection to your KMC Converge AX installation, going to the License Manager, and ensuring you have both a cse.license fi le under the License Files section, and a cse.certifi cate fi le under the Certifi cate Files section. Also, restart your Platform Daemon, KMC Converge AX, and Station if you have only recently been licensed.


Template Folder: See the section Templates on page 15 for information on using templates.

All of these properties do not need to be setup or tampered with, however, ensure you have at least set a desired Title, Icon, and Current Time Ord, and that your License Mode shows as being “Registered.”

Mobile AppsKMC Converge GFX utilizes the mobile apps in KMC Converge AX to allow for HTML-based interaction with alarm consoles, schedules, histories, and more, on desktop computer web browsers as well as mobile device web browsers. Follow these steps to install them:1. Locate the Apps component in your running station in KMC Converge AX. It

should be directly under the Config section.

2. Double click on it to open the App Manager.3. Hit the New button at the bottom and add in the Mobile Alarm Console App.4. Repeat the previous step for the Mobile History App, Mobile Property Sheet

App, Mobile Px App, and Mobile Schedule App.


User setupIn order to view the mobile apps in a web browser, the logged-in user must be setup for a Mobile Profi le and their Nav fi le must point them at the graphics generated by KMC Converge GFX. To assist with setting up a user account to use KMC Converge GFX, the kmcConvergeGfx palette contains a kmcguest user object, which you can drag into your UserService to edit and use. To setup a user yourself, follow these steps:1. Set the Default Web Profile to Default Mobile Web Profile.

• Set Show Header to Show• Set Show Header Back Button to Show• Set Show Select Views to Hide• Set Show Home to Hide• Set Show Logout to Hide

2. Follow the previous steps for the Mobile Web Profile settings as well.3. Once your KMC Converge GFX graphics have been generated, set the user’s

Nav File to point at your site’s nav file, which is generated in the File space of the station, under a folder named after your graphics’ Site Name.

4. Ensure the user has appropriate permissions for, at the least, read-level access to all related points, files, and histories used by the KMC Converge GFX site.

Confi guring Graphics

Items

Creating customized graphics with KMC Converge GFX consists of stacking various confi gured “Items” that are then displayed in their corresponding order on a web page. Items can be nested to create a hierarchical tree structure of navigation.


Value Items

Value Items are primarily used to show the output value of components and points from your KMC Converge AX station, and also to provide hierarchy and structure to your KMC Converge GFX navigation. They can be confi gured to show up to four different values within a single Value Item, and by placing items within them, they can create links to provide navigation into deeper levels of your graphics.

Name: The name of the actual item component within your KMC Converge AX station. This name must be unique to all other items. It will also be displayed on your fi nal KMC Converge GFX graphics, unless you specify an Html Display Name.

Html Display Name: If specifi ed, this fi eld will be shown as the item name in your fi nal KMC Converge GFX graphics. This can be useful if you desire duplicate names within the same graphic page. For example, the Niagara framework will not allow you to have several components named “SpaceTemp” within the same folder, and will rename them “SpaceTemp1, SpaceTemp2, etc…”. By using a Html Display Name, you can show whatever name you want on your graphics.

Icon Img: This allows you to select an icon for the Item. Click the icon for a list of available icons.

Icon Ord: This allows you to specify a custom icon for the Item, which you can choose from the fi le system of your station. Custom icons are sized proportionally to fi t either the width or height of the available icon space.

Background Status: Allows you to animate the background of the Name portion of your Value Item. The status of any Ord specifi ed in this fi eld will be used to animate said background.

Html Style: This is an advanced fi eld for adding a “style” attribute to the HTML of the item. You can put CSS code in this fi eld to customize your item as desired.

Is Parent: Enables the alternate “Parent” styling defi ned in your CSS Template. Also has a slightly larger font size.

Value Items have four unique sections of properties that represent each of the possible four values you can show for a ValueItem. If you leave them empty, they will not be used at all (however the ValueItem can still provide functionality for navigation, acting as more of a folder). The properties for these sections are described as follows:

Html Display Name: If specifi ed, this name will be shown above the corresponding value output. If left empty, the name will default to the actual name property of the selected Value Ord.

Value Ord: Use the Component Chooser to select an Ord from your station. The output value of this ord will be subscribed to and shown in your KMC Converge GFX. Note: the component you link to must have some kind of “out” slot, or else it will not func on properly.

Action Link: Can be set to None (default), Quick Action, or Property Sheet. None will show only the value output. Quick Action will show a pencil icon on the value, indicating that the user can click on it to open a menu which provides a list of all available actions for the logged-in user. Also includes a button to link to


the Property Sheet. Property Sheet will immediately open the Property Sheet for the item, which also has the ability to execute any available actions. Note: Action slots with the “Hidden” flag set on them in KMC Converge AX will not be shown by Quick Actions.

Example of Quick Actions being set for a Value Item’s Value1 Action Link

Background Status: If set to true, the status of the Value Ord will be reflected in the background of the value.

Hide Display Name: If set to true, no display name will be shown above the Value Ord’s output. This can be useful to shown a single value for a Value Item.

Example of setting Hide Display Name to true

By inserting items within a ValueItem, you can create hierarchical navigation. To easily do this, hit the arrow icon in the “Open” column of the “K M C Service View” where you are editing your items:

When viewing your graphics in a web browser, an arrow icon indicates that the Name portion of your ValueItem can be clicked on to navigate into a deeper page of your graphics:


Hyperlink Items

Hyperlink Items can be used to provide a hyperlink to any web address.

Name: The name of the item component within your KMC Converge AX station and also used to display on the Hyperlink Item itself in your web graphics. This name must be unique to all other items.

Icon Img: This allows you to select an icon for the Item. Click the icon for a list of available icons.

Icon Ord: This allows you to specify a custom icon for the Item, which you can choose from the fi le system of your station. Custom icons are sized proportionally to fi t either the width or height of the available icon space.

Hyperlink Attribute: Can be set to Blank, or Self. Blank will make the hyperlink show up in a new tab or window when clicked on in a web browser. Self will make the hyperlink show up in the current tab/window.

Hyperlink: The actual hyperlink. You can type any HTTP address in this fi eld, or, you can use the Component Chooser or File Ord Chooser to link to actual locations in your station.



Schedule Items

Schedule Items are used in conjunction with the Mobile Schedule App to provide access to viewing and editing schedules from your KMC Converge GFX graphics on any size device.



Schedule Ord: Set this to point to your desired schedule. Doing so will make the schedule editor for that schedule appear immediately upon clicking on the Schedule Item in your graphics. If this fi eld is left null, the user will be given a list of all schedules in the station upon clicking on the Schedule Item in the graphics, and can choose which schedule they want to look at.




Alarm Items

Alarm Items are used in conjunction with the Mobile Alarm App to provide access to viewing and editing alarms from Alarm Consoles in your KMC Converge AX station on any size device. Also, the Alarm Item displayed in your web graphics will flash red if there are any associated alarms that are currently In Alarm, and a number next to the name of the Alarm Item will indicate how many Unacknowledged Alarms there are.



Alarm Ord: Set this to point to your desired Alarm Console. Doing so will make the specifi ed Alarm Console appear immediately upon clicking on the Alarm Item in your graphics. This fi eld should not be left null, or else the In Alarm red flashing and Unacknowledged Alarm count features of the item will not function.



History Items

History Items are used in conjunction with the Mobile History App to provide access to viewing history charts and tables on any size device.


Html Display Name: If specifi ed, this fi eld will be shown as the item name in your fi nal KMC Converge GFX graphics. This can be useful if you desire duplicate names within the same graphic page. For example, the Niagara framework will not allow you to have several components named “SpaceTemp” within the same folder, and will rename them “SpaceTemp1, SpaceTemp2, etc…”. By using an Html Display Name, you can show whatever name you want on your graphics.


History Ord: Set this property to your desired history, or history group. If set to a history, the user will be taken to a screen where they can view a line chart or history table for that history. If set to a group or device containing many histories, they will have the ability to expand that group and select what history they would like to view.



Item Separators

Item Separators are a simple item for creating space on a page. They can be used to divide up different sections of items for an enhanced user experience.

Name: The name of the actual item component within your KMC Converge AX station. This name must be unique to all other items.

Pixel Size: How many pixels of space (height) to insert within your KMC Converge GFX item structure.

Image Items

Image items can be used to insert a banner image across your page. In order to remain responsive and display well on all size devices, whatever image you specify will stretch proportionally until its width is that of the current sized graphics. If you do not wish for your image to be so wide, consider adding extra space to both sides of the image in an image editor.


Image Ord: Use the File Ord Chooser to set this to an image fi le in your station. Supports any image fi les supported by common web browsers.


Iframe Items and MobilePx graphics

Iframe Items can be used to embed web pages into your KMC Converge GFX graphics. It will not work for all websites, as some sites prohibit this functionality. However Niagara web pages do not prohibit this, and accordingly, even other web pages from your KMC Converge AX station can be embedded into KMC Converge GFX, which includes MobilePx graphics.


File Ord: Path to whatever is to be embedded into the Iframe. Needs to be a valid HTTP web address, or a valid path to a view in your KMC Converge AX station.

Height Size: The width of the Iframe will match the width of your device-sized graphics, however the height must be set manually. The height you set is in pixels. They are relevant to the largest sized desktop graphics.

Dynamic Height: If set to true, the height of your Iframe will scale relative to the width and height of the Iframe when viewed on the largest sized desktop


graphics. This is recommended to be set to True in most cases.


If you would like to include more traditional Px graphics within your KMC Converge GFX site, you can create Mobile Px pages and use the Iframe item to embed them. Follow these steps to create a MobilePx graphic and embed it into KMC Converge GFX:1. Right click on a desired folder or device within the Config of your station,

expand Views, and click on New View.2. Type a name for your view, and set the Target Media to MobilePx Media.

This creates a MobilePx file for you, and also the View. MobilePx files on their own do not render in a web browser unless they are a View on some-thing in the Config.

3. After you hit Ok you will be taken to the Px Editor. Open the mobile palette, and expands Widgets. Click and drag a CanvasPane into your MobilePx page. Set the width and height of it to something sensible, and set the scale field to FitRa o.

4. Create your MobilePx graphic. Keep in mind: advanced bindings, third-party Px widgets, and PxIncludes are examples of things that do not work in Mobile Px files. You are mostly limited to images and labels, and their standard animation features.

5. After finishing your graphic, make an Iframe Item, and use the Component Chooser to set the File Ord to the folder or device that contains your


MobilePx View. Make sure the Height Size property is tall enough to fit your graphic.

HTML Items

HTML Items are advanced items that allow you to insert any HTML code you’d like into the content flow of your KMC Converge GFX graphics.


Html Code: Everything in this fi eld will be inserted directly into the HTML of your page, right where the item is placed in the Item structure of your page. By default, it is populated with some HTML that will make an item that looks similar to other

Reordering items

In the row of buttons at the bottom of the KMC Service View where you edit your Items, there is a Reorder button. This can be used to rearrange the order of your items or sort them.


Templates

Templates can be used to create a set of confi gured items, that can be mass-created on demand, relative to a path in your KMC Converge AX station. You can confi gure items to have relativized paths, such as “slot:SpaceTemp”, and when you drag in a Points folder and use a template on it, that relative path will be replaced with “station:|slot:/Path/to/Points/folder/SpaceTemp”. This allows you to create one Template that can be used to mass generate repetitive graphics (for example, you could have one VAV template that is used for several dozen VAV graphic pages). Follow these steps to create a template:

1. Double click on the Template Folder , which is located directly under the KMC Converge GFX Service.

2. In this KMC Template Folder View, you can create a new template. Hit the New button and do so.

3. Double click on your new Template to go into the KMC Template View.4. The KMC Template View operates just like the KMC Service View. You can

add Items just the same. You can even create a nested structure by adding Items into your Value Items.

5. Items in the KMC Template View can contain relative paths. When the Template is used, it searches for any Ord paths that start with “slot:”. That string is then replaced by the actual path to the KMC Service View.

6. Once your template is finished, drag any component from your Station’s Config section into the normal KMC Service View. Upon doing so, a Template Selection window will pop up, allowing you to pick a template.

7. Once you select Use Template, all of the items in the template will be added to your current KMC Service View page, and all relative paths will be edited to the path of what you have dragged in.

8. If at first you don’t succeed, delete the items, edit the Template, and drag your folder in again!


Generating Graphics

KMC Automatic Site Build

KMC Converge GFX contains a function for fi nding any Bacnet devices in the station that have a KMC Application in them with a GraphicalPoints folder, and automatically generating a set of KMC Converge GFX graphics for all of the points in that folder. To do this, simply hit the Build Site button on the KMC Service View. KMC Devices will be created in your KMC Converge GFX site.

These KMC Devices can be rearranged and reorganized wherever you’d like in your KMC Converge GFX Service. You can also add more Items into them. If you hit Build Site again, your existing KMC Devices will not be tampered with. If you’d like to recreate them, simply delete the existing device and hit Build Site again.

Generate Site / Generate Page

One you have fi nished confi guring your graphics, you must Generate them to create your HTML pages and have something to look at in your web browser. At any time, you can hit Generate Site to do so.

Generate Site will regenerate your entire site. Every single page will be checked for changes and created. If you create a very large KMC Converge GFX site, this can take a while.

Generate Page will give you the option of only generating the current page you are viewing in your Service, or the current page as well as all of its descendants.

If you are actively viewing graphics in a web browser upon triggering a Generation, be sure to refresh your browser to see your changes.


Customizing the CSS Template The CSS Template is located directly under the KMCConvergeGFXService, and contains properties to control the colors and other style properties used in your KMC Converge GFX site.

Properties

Background Color: This controls the overall background color, which is seen if you do not use a Background Image.

Background Image: An image to use for the background of your site. This image will be sized proportionally to fi t the width and height of the user’s current browser window.

Font: The font used for your KMC Converge GFX Site. The options available are web-safe, and should render well on any platform (Windows, Mac, iOS, Android, etc).

Header Background Color: The background color of your header. Use the “Alpha” property of the color chooser for semi-transparent colors.

Header Height: The height (in pixels) of your header. Increase this if your Title Image is too tall.

Header Text Color: The color of the text in your header.

Title Image: Path to an image to use in your header. Will be placed on the left, vertically centered. No stretching or sizing is performed on this image, so point this to an appropriately sized image.

Navbar Background Color: The background color of your Navbar. Use the “Alpha” property of the color chooser for semi-transparent colors.

Navbar Hover Color: The background color of your Navbar when a user hovers their cursor over an option.

Navbar Text Color: The color of the text in your Navbar.

Navbar Icon Color: The color of all icons in your Navbar.

Navbar Margin Bottom: The vertical height (in pixels) between your Navbar, and the fi rst items on your page.

Banner Margin Bottom: The vertical height (in pixels) directly below any Image Items.

Parent Background Color: The background color of all items with their Is Parent property set to true. Use the “Alpha” property of the color chooser for semi-transparent colors.

Parent Hover Color: The background color of all Parent items when the user hovers over them with their cursor.

Parent Text Color: The color of the text in Parent items.

Parent Icon Color: The color of all icons in Parent items.

Parent Margin Bottom: The vertical height (in pixels) directly below any Parent Items.

Child Background Color: The background color of all items with their Is Parent


property set to false. Use the “Alpha” property of the color chooser for semi-transparent colors.

Child Hover Color: The background color of all Child items when the user hovers over them with their cursor.

Child Text Color: The color of the text in Child items.

Child Icon Color: The color of all icons in Child items.

Child Margin Bottom: The vertical height (in pixels) directly below any Child Items.

Import / Export

CSS Templates can be exported and imported. To do so, hit the icon next to the Import Export property under your CSS Template. Hit Import to select a cssTemplate.xml fi le from your workstation. Hit Export to create a cssTemplate.xml fi le of your current CSS Template.

Documents

KMC Converge GFX User's Guide