Crestron SSI User guide

Type
User guide

This manual is also suitable for

Crestron Fusion® Software SSI Model
Reference Guide
Crestron Electronics, Inc.
Original Instructions
The U.S. English version of this document is the original instructions.
All other languages are a translation of the original instructions.
Crestron product development software is licensed to Crestron dealers and Crestron Service Providers (CSPs) under a
limited nonexclusive, nontransferable Software Development Tools License Agreement. Crestron product operating
system software is licensed to Crestron dealers, CSPs, and end-users under a separate End-User License Agreement.
Both of these Agreements can be found on the Crestron website at www.crestron.com/legal/software_license_
agreement.
The product warranty can be found at www.crestron.com/warranty.
The specific patents that cover Crestron products are listed at www.crestron.com/legal/patents.
Certain Crestron products contain open source software. For specific information, visit www.crestron.com/opensource.
Crestron, the Crestron logo, .AV Framework, AirMedia, CaptureHD, Crestron Connected, Crestron Fusion, Crestron
Mercury, Crestron Studio, Crestron Toolbox, DM, and RoomView are either trademarks or registered trademarks of
Crestron Electronics, Inc. in the United States and/or other countries. Blu-ray Disc is either a trademark or a registered
trademark of Blu-ray Disc Association (BDA) in the United States and/or other countries. Bluetooth is either a
trademark or registered trademark of Bluetooth SIG, Inc. in the United States and/or other countries. Microsoft and
Skype are either trademarks or registered trademarks of Microsoft Corporation in the United States and/or other
countries. Other trademarks, registered trademarks, and trade names may be used in this document to refer to either
the entities claiming the marks and names or their products. Crestron disclaims any proprietary interest in the marks
and names of others. Crestron is not responsible for errors in typography or photography.
©2019 Crestron Electronics, Inc.
Contents
Introduction 1
Reports 2
Report Attributes 3
DeviceUsage 3
Device Usage Reporting 3
Display Usage Reporting 4
Call Usage Reporting 4
RoomOccupied 5
DisplayPowerIsOn 6
DisplayUsage 6
OnlineStatus 6
ErrorMessage 7
SystemPowerIsOn 8
Approved Asset Types 9
SSI Programming 11
Add the Fusion Room Device Definition 12
Add Assets to the Fusion Room Device Definition 14
Add the Fusion SSI Module to a Program 16
Programming Procedure 16
Signal Definitions 20
Program the Time Functions 30
Programming Procedure 30
Program the Fusion SSIDisplay Usage Module 31
Programming Procedure 31
Signal Definitions 34
Program the Fusion SSI Device Usage Module 35
Programming Procedure 35
Signal Definitions 38
Program the Fusion SSI Equipment Status Module 39
Programming Procedure 39
Signal Definitions 42
Reference Guide — 7898E Contents • i
Program the Fusion SSI Help Request and Response Module 43
Programming Procedure 43
Signal Definitions 45
Program the Fusion SSI Broadcast Message Module 47
Programming Procedure 47
Signal Definitions 49
Program the Fusion SSI Text Message Send and Receive Module 51
Programming Procedure 51
Signal Definitions 53
Program the Fusion SSI Scheduling Awareness Module 55
Programming Procedure 55
Signal Definitions 56
Crestron Fusion Request/Response XML Streams 61
Basics 61
Data Fields 62
Schedule Requests 63
Full Schedule Request 63
Filtered Schedule Request(AllMeetings) 63
Filtered Schedule Request(Specific Meeting) 64
Schedule Response 65
Meeting End Time Change Request 67
Meeting End Time Change Response 67
Room List Request 68
Room List Response 69
Room Configuration Request 70
Room Configuration Response 70
Remove Schedule Request 71
Remove Schedule Response 71
Create Schedule Request 72
Create Schedule Response 72
Room Attribute List Request 73
Query to Change the State of an Attribute(Write) 73
Query to Obtain the State of an Attributeby Join (Read) 73
Query to Obtain the State of an Attributeby Name (Read) 73
Room Attribute List Response 74
Room Attribute Change Request 74
Room Local Time Request 74
Room Local Time Response 74
Help Request 75
HelpRequest (Initiation) 75
HelpResponse 75
ii • Contents Reference Guide — 7898E
HelpClose 75
HelpCancel 75
Get OpenIssues 76
Get OpenIssues Response 76
Room Schedule Request for Current/Next Meeting 77
Glossary 78
Appendix A: Filtered Schedule Request Fields 79
Reference Guide — 7898E Contents • iii
iv Contents Reference Guide 7898E
Reference Guide — 7898E Crestron Fusion® Software SSI Model 1
Introduction
Programming is at the core of any successful Crestron Fusion® software deployment. The
Single System Interface (SSI)is a programming model that ensures Crestron Fusion has
consistent data sets across all devices regardless of the integrator, programming
language, or application.
This document describes the data that applications must provide in order to be
SSIcompliant and provides guidelines to programmers that are implementing Crestron
Fusion support in their code.
Since the SSIattributes are a standardized set of data that allows Crestron customers to
use built-in reports in Crestron Fusion, it is critical that all applications provide data in a
consistent manner. This document focuses on the application provider and includes all
relevant implementation notes and testing instructions.
The SSImodel provides the following:
l Signal naming conventions
l Behavior logic
l Join number guidelines
l Programmed asset models
l Scalability
l Predictable outcomes
2 • Crestron Fusion® Software SSI Model Reference Guide — 7898E
Reports
Providing generated reports is one of the primary functions of Crestron Fusion software
and the SSImodel. Crestron Fusion reports typically include a visual chart of a particular
data set. Each report has different customization options, including visualization,
aggregation type, assets to display, and meeting type (depending on the report type), which
allows for numerous different combinations.
The following reports are included in Crestron Fusion software:
l Device Usage by Meeting
l Device Usage Totals
l Meeting by Room
l Booking and Occupancy
l Call Statistics
l Device Usage
l Display Usage
l Display Usage (Current)
l System Usage
l Error Alerts
l Room Occupancy
Reference Guide — 7898E Crestron Fusion® Software SSI Model 3
Report Attributes
This section describes the attributes (signals)that are required to supply reports in
Crestron Fusion with the necessary data.
DeviceUsage
The DeviceUsage attribute is used to report device usage in a room. Each device in the
system is monitored for usage in minutes, and the usage string is sent to Crestron Fusion
following the DeviceUsage string format.
Behavior:A device is considered in use when it is the current active source in the room and
is presenting data.
DeviceUsage Attribute
Field Value Notes
Attribute
Name
DeviceUsage
Join 5
Type Serial
Report
Level
Room
Expected
Values
Formatted string as shown in the following sections
Used in
Reports
l Device Usage by Meeting
l Call Statistics
l Device Usage
l Device Usage Totals
l Display Usage
C#Field
FusionRoom.DeviceUsage.InputSig.StringValue
Device Usage Reporting
The data for Device Usage reporting is formatted as follows:
USAGE||Date_Stamp||Time_Stamp||TIME||Asset_Type||Asset_Name||-||Asset_
Usage||-||-||-||
Device Usage Reporting
Parameter Meaning
Date_Stamp Current date in YYYY-MM-DD format
Time_Stamp Current time in HH:MM:SSformat
Asset_Type This field must match the Asset Type as registered in
Crestron Fusion.
4 • Crestron Fusion® Software SSI Model Reference Guide 7898E
Parameter Meaning
Asset_Name This field must match the Asset Name as registered in
Crestron Fusion.
Asset_Usage The usage in minutes. If the value is less than zero, it is
ignored.
The strings USAGE and TIME are fixed and must be in all caps.
Example: USAGE||2016-10-26||12:34:39||TIME||Source||Room PC||-||4||-||-
||-||
The USAGEstring must also be connected to the "Device Usage"signal pair Fusionroom
slot 3.
Display Usage Reporting
The data for Display Usage reporting is formatted as follows:
USAGE||Date_Stamp||Time_Stamp||TIME||DISPLAY ||Asset_Name||-||Asset_
Usage||-||-||-||
Display Usage Reporting
Parameter Meaning
Date_Stamp Current date in YYYY-MM-DD format
Time_Stamp Current time in HH:MM:SSformat
Asset_Name This field must match the Asset Name as registered in
Crestron Fusion.
Asset_Usage The usage in minutes. If the value is less than zero, it is
ignored.
The strings USAGE,DISPLAY, and TIME are fixed and must be in all caps.
Example: USAGE||2016-10-26||12:34:39||TIME||DISPLAY||Left Display||-
||4||-||-||-||
The application should not send Display Power Feedback, as Crestron Fusion will also
generate these sessions.
Call Usage Reporting
The data for Call Usage reporting is formatted as follows:
USAGE||Date_Stamp||Time_Stamp||CALL||Asset_Type||Dial_
Type||Number||Call_Duration||Call_Status||-||-||
Call Usage Reporting
Parameter Meaning
Date_Stamp Current date in YYYY-MM-DD format
Time_Stamp Current time in HH:MM:SSformat
Reference Guide — 7898E Crestron Fusion® Software SSI Model 5
Parameter Meaning
Asset_Type This field must match the Asset Type as registered in
Crestron Fusion. This will be “Dialer” for Crestron Mercury®
system, or it can be an “Audio Codec” or “Video Codec” as
appropriate.
Dial_Type For Crestron Mercury, this can be USB, SIP, Skype®
conferencing solution, or Bluetoot technology. For Video
and Audio Codecs, the dial type will be "Video" or "Audio".
Asset_Usage The usage in minutes. If the value is less than zero, it is
ignored.
Number The number (or address) dialed, "-" if not defined.
For Skype, this "Call_Number" is variable depending on the
connection (Meeting = URL, P2P = email address or number).
Call_Duration Length of the call in minutes. If this field is less than one
minute, the system rounds up.
Call_Status Valid values are "success" or "failure". A "failure" value can
be caused by a missed call, no answer, or no connection.
RoomOccupied
The RoomOccupied attribute is used to report occupancy in a room.
Behavior:A room is considered occupied when either of the following are true:
l An occupancy sensor in the room detects occupancy
l The room is in a call (drives occupancy high)
Use the FusionOccupancySensor class in SIMPLSharp Pro or the
FusionOccupancySensor in SIMPL programming software to ensure that the proper
signal is used.
NOTE:The Room_Occupied signal programming is required for Crestron Fusion to
produce the corresponding occupancy sessions in reports. Room_Occupied must have
logging enabled in Crestron Fusion.
RoomOccupied Attribute
Field Value Notes
Attribute Name RoomOccupied
Join 10
Type Asset (Occupancy Type)
Report Level Digital
Expected Values 1 or 0
Used in Reports
l Device Usage by Meeting
l Meetings by Room
6 • Crestron Fusion® Software SSI Model Reference Guide 7898E
Field Value Notes
l Device Usage Totals
l Room Occupancy
l Booking and Occupancy
DisplayPowerIsOn
Do not implement this attribute, as it conflicts with DeviceUsage and creates overlapping
usage sessions in Crestron Fusion. Use the FusionSSIDisplay Usage module instead.
DisplayUsage
The DisplayUsage attribute used to report display usage (projector and/or LCDs and other
displays) in a room. This report requires that the DisplayUsage signal must be
programmed for each room.
Display usage values in rooms with multiple projectors or multiple lamps/projectors should
show the highest value in hours across all displays in the room. If the room has both
projectors and LCDs/other displays, only lamps/projectors should be considered for this
value. Individual displays report their usage to the Utilization attribute at the asset level
and do not appear on the report.
NOTE:.AVFramework™ software currently sends this attribute for each individual
asset.
DisplayUsage Attribute
Field Value Notes
Attribute Name DisplayUsage
Join 2
Type Analog
Report Level Roomlevel
Expected Values Reported lamp hours
Used in Reports Display Usage (Current)
OnlineStatus
The OnlineStatus attribute is determined by Crestron Fusion. It shows the status of the
CIPconnection between Crestron Fusion and the device.
Reference Guide — 7898E Crestron Fusion® Software SSI Model 7
ErrorMessage
The ErrorMessage attribute reports when a device is in an error state. Any device
connected to the system must send a notification (a formatted error message) to
Crestron Fusion when the device has a connection status change. The system detects the
condition and sends the appropriate notification, including sending a "0":status on
connection restored.
DisplayUsage Attribute
Field Value Notes
Attribute Name ErrorMessage
Join 2
Type Serial
Expected Values Formatted string as shown in
the text following this table
Used in Reports Error Alerts
The string must be formatted as follows:<error severity>:<msg> where <error
severity> is a severity code ranging from 0 to 4, and <msg> is the error message.
The severity levels are as follows:
l 0 = OK (when the device is no longer in an error condition)
l 1 =Notice
l 2 = Warning
l 3 = Critical (A device that is not reporting but the room is still operational for
meetings)
l 4 = Fatal (Any condition that renders the room or system unusable)
NOTE:All offline conditions will either be a 3 or 4 severity level.
Send an error notification whenever a device in the system stops reporting to the
processor, and clear the error when it reconnects. Other notifications can be sent as
determined by the programmer.
The message format for SSIis <asset name>:<status>.
8 Crestron Fusion® Software SSI Model Reference Guide 7898E
Examples:
4:Display1 Offline
0:Display1Online
3:DVDPlayer Offline
0:DVDPlayerOnline
4:Display1 Offline
0:Display1Online
3:Cable Box Offline
0:CableBox Online
When the system first boots up, a timer should be created. If devices do not connect
before the timer elapses, an error should be generated. The default time is 60 minutes.
SystemPowerIsOn
The SystemPowerIsOn attribute indicates that the room is in any state other than "Room
Off", regardless of the device that is being used. This attribute is used to create the
SystemUsage report. Power alone is not a consideration for this attribute; only system or
room usage is considered.
SystemPowerIsOn Attribute
Field Value Notes
Attribute Name SystemPowerIsOn
Join 3
Type Digital
Report Level Room
Expected Values 1 or 0
Used in Reports System Usage
Reference Guide — 7898E Crestron Fusion® Software SSI Model 9
Approved Asset Types
The following table lists the approved Asset Types that should be used for consistency.
Asset Types
Asset Type Notes Severity
AccessPoint 4
Amplifier 3
AudioCodec 4
Blu-ray Disc® Player 3
Cable Box 3
CDPlayer 3
Computer 3
Controller 4
Dialer 4
Display 4
DMReceiver 3
DMTransmitter 3
DocumentCamera 3
DSP 4
DVDPlayer 3
Energy Load CrestronFusion® EMAsset N/A
Energy Logging CrestronFusion® EMAsset N/A
Energy Supply CrestronFusion® EMAsset N/A
Keypad 4
Gateway 4
Lighting Load CrestronFusion® EMAsset N/A
Lighting Scenes CrestronFusion® EMAsset N/A
Media Player 3
Network Switch 4
OccupancySensor 3
Photocell 3
Power Conditioner 3
PresentationGateway 4
10 Crestron Fusion® Software SSI Model Reference Guide — 7898E
Asset Type Notes Severity
Projector 4
Scaler 3
Schedule Display 3
Shade Load CrestronFusion® EMAsset N/A
ShadePresets CrestronFusion® EMAsset N/A
Switcher 4
Touchpanel Includes preloaded drivers for all scheduling touch screens 4
UCDevice 4
UCSoftware 3
VCR 3
VideoCapture Includes preloaded driver for CaptureHD® system 3
VideoCodec Includes preloaded driver for CaptureHD® system 4
Whiteboard 3
Reference Guide — 7898E Crestron Fusion® Software SSI Model 11
SSI Programming
This section provides detailed information on programming SSI modules with SIMPL
software for Crestron Fusion® software. The content in this section is intended for use by
Crestron® software programmers. Use the provided procedures and signal explanations
for each module to successfully program a Crestron Fusion deployment.
The following should be completed prior to programming with Crestron Fusion
SSImodules:
l The scope of work has been determined and stakeholders have defined the
functionality and features of the Crestron Fusion deployment.
l The programmer has completed the functional programming in the room.
Functional programming is defined as any programming required that automates
the room with control and feedback.
l A program has been created with a processor defined, and functional programming
has been completed substantially.
The procedures in this document must be followed in order. Before using these procedures,
review the following SIMPL programming flow diagram.
SIMPLProgramming FlowDiagram
12 • Crestron Fusion® Software SSI Model Reference Guide — 7898E
Add the Fusion Room Device Definition
The Crestron Fusion device definition (listed as "Fusion Room"in the Crestron Fusion
database) is required for Crestron Fusion programming. The Fusion Room device
definition permits information to pass to and from the Crestron Fusion server and is the
base for implementing CrestronFusion code to the program.
To add the Fusion Roomdevice definition in SIMPL:
1. Ensure all prerequisites have been met as described above.
2. Add the Fusion Room device definition to the program. The definition is located
under Crestron Devices > Ethernet Control Modules > Ethernet based Crestron
Software Applications.
Fusion Room Device Definition
Reference Guide — 7898E Crestron Fusion® Software SSI Model 13
The user can also right-click the Ethernet subslot for the processor and then add the
Fusion Room device definition.
Ethernet Subslot
14 • Crestron Fusion® Software SSI Model Reference Guide — 7898E
Add Assets to the Fusion Room Device Definition
Assets in Crestron Fusion encompass a broad spectrum of items in a room, ranging from
AVequipment to furniture, drapes, and lighting fixtures. The Static Asset is used to define
these assets.
NOTE:The Fusion Room device definition must be added to the program prior to adding
assets. For more information, refer to Add the Fusion Room Device Definition (on
page12).
To add assets to the FusionRoom device definition in SIMPL:
1. Ensure all prerequisites have been met as described above.
2. Select the Configure view.
3. Right-click the Fusion Room device definition.
4. Select Add Item to Fusion Room. The Select New Device dialog box is displayed.
5. Select Fusion Static Asset from the list.
Select New Device Dialog Box
  • Page 1 1
  • Page 2 2
  • Page 3 3
  • Page 4 4
  • Page 5 5
  • Page 6 6
  • Page 7 7
  • Page 8 8
  • Page 9 9
  • Page 10 10
  • Page 11 11
  • Page 12 12
  • Page 13 13
  • Page 14 14
  • Page 15 15
  • Page 16 16
  • Page 17 17
  • Page 18 18
  • Page 19 19
  • Page 20 20
  • Page 21 21
  • Page 22 22
  • Page 23 23
  • Page 24 24
  • Page 25 25
  • Page 26 26
  • Page 27 27
  • Page 28 28
  • Page 29 29
  • Page 30 30
  • Page 31 31
  • Page 32 32
  • Page 33 33
  • Page 34 34
  • Page 35 35
  • Page 36 36
  • Page 37 37
  • Page 38 38
  • Page 39 39
  • Page 40 40
  • Page 41 41
  • Page 42 42
  • Page 43 43
  • Page 44 44
  • Page 45 45
  • Page 46 46
  • Page 47 47
  • Page 48 48
  • Page 49 49
  • Page 50 50
  • Page 51 51
  • Page 52 52
  • Page 53 53
  • Page 54 54
  • Page 55 55
  • Page 56 56
  • Page 57 57
  • Page 58 58
  • Page 59 59
  • Page 60 60
  • Page 61 61
  • Page 62 62
  • Page 63 63
  • Page 64 64
  • Page 65 65
  • Page 66 66
  • Page 67 67
  • Page 68 68
  • Page 69 69
  • Page 70 70
  • Page 71 71
  • Page 72 72
  • Page 73 73
  • Page 74 74
  • Page 75 75
  • Page 76 76
  • Page 77 77
  • Page 78 78
  • Page 79 79
  • Page 80 80
  • Page 81 81
  • Page 82 82
  • Page 83 83
  • Page 84 84
  • Page 85 85
  • Page 86 86

Crestron SSI User guide

Type
User guide
This manual is also suitable for

Ask a question and I''ll find the answer in the document

Finding information in a document is now easier with AI