You're currently browsing the Ignition 8.0 docs. Click here to view the latest docs.


Perspective offers a collection of Session Events designed to allow the Gateway to track and interact with the session at critical moments. Specifically, they are scripts that run in the Gateway when a session starts up, shuts down, or runs a Native App Action.

There are five configurable session events in Perspective:

  • Startup
  • Shutdown
  • Barcode Scanned
  • Bluetooth Device Data Received (new in 8.0.5)
  • NFC NDEF Scanned
  • Accelerometer Data Received
  • Message (new in 8.0.7)

Although they are designed to handle Session Events, the scripts that you write will be run in a Gateway scope, not a Session scope.

Configuring Session Events

To start working on a session event script:

  1. In the Project Browser, double-click on the Session Events section:



  2. The Session Events dialog will appear:



  3. Configure a script by selecting one of the events on the left-hand side.

On this page ...


Startup and Shutdown Event Scripts

Startup and Shutdown events run, naturally, whenever a session starts or ends. In each case, the gateway will have access to the session object associated with the section, complete with all session properties.

When designing a startup or shutdown event script:

  • Custom session properties can be used to pass any additional information to the gateway, or, in the case of a startup script, to pass information to the newly opening session. You can configure custom session properties from the Page Configuration dialog, by clicking on the Settings  icon in the Designer.
  • A shutdown event script will run specifically when a session is ending. This happens specifically when any of the following events occur:
    • The session closes due to a timeout. Session timeout is configurable in the Perspective > General section of Project Properties in the Designer
    • The user is no longer authorized to run the session.
    • The redundancy system determines that the Gateway is inactive.
    • The licensing system no longer permits the user to run the session.
    • The project is no longer runnable.
    • The project is deleted.


Closing the browser tab with the session will not immediately close the session; the session must first time out.

Startup and Shutdown Example

This example will record the session start and end time to the database.

  1. For this example, we need to set up a few queries that we can use to write our data to the database.
  2. Make a new named query called Startup Query.
    1. Set the Query Type to Update Query.
    2. Set up a single Value type parameter with a name of SessionID and a datatype of string.

    3. Add the query:

      INSERT INTO sessions (session_id, start_time)
VALUES (:SessionID, CURRENT_TIMESTAMP)
  3. Make a second new named query called Shutdown Query.
    1. Set the Query Type to Update Query.
    2. Set up a single Value type parameter with a name of SessionID and a datatype of string.

    3. Add the query:

      UPDATE sessions 
SET end_time = CURRENT_TIMESTAMP
WHERE session_id = :SessionID
  4. Next, we need to add Session Events so that Perspective knows to run those queries on startup and shutdown.
  5. Under the Project tab, select Session Events.



  6. On the Session Events screen, click the Startup  icon. 

  7. Add the following script to the page: 

    # This script will record the time when the session is opened.
	
	# Create the parameters
	queryParams = {'sessionID':session.props.id}
	
	# Run the query
	system.db.runNamedQuery('My Project', 'Startup Query', queryParams)



  8. Click Apply and then click the Shutdown  icon.



  9. Add the following script to the page: 

    # This script will record the time when the session times out. Note that after the session is closed,
# the session won't time out until the time out period is reached..
	
	# Create the parameters
	queryParams = {'sessionID':session.props.id}
	
	# Run the query
	system.db.runNamedQuery('My Project', 'Shutdown Query', queryParams)
  10. Click OK.
  11. Save your project.

Test the Example

To test the example, open the Perspective App on your mobile device and load the project. 

  1. You should see a new entry in the database table with the time the time the session was started as well as the session id.
  2. After the session times out (such as after it is closed) you should see the original entry get updated to include the new shutdown time.


Native App Event Scripts

When the Perspective App is running on a mobile device, it enables users to use tools available on the device, such as GPS location data, the camera, or the accelerometer. The remaining session events are designed specifically to handle the three Native App Actions.


Barcode Scanned

The scanned barcode action can make use of a mobile device's built in camera.

ArgumentsDescription
sessionAn object that references the project session that called the Barcode Scanned event. Use this to identify the specific session that scanned the barcode.
data

The data returned from the barcode scan. Access the underlying barcode data using:

data.text
contextThe user defined context object that can be defined on the action.

Barcode Scanned Example

This example will scan a barcode, and write its value to a tag.

  1. For this example, drag a Button component and a Label component onto a view. 
  2. Create a new memory Tag with a data type of String. Set the value to "Please scan a barcode."



  3. Bind the text of the label to the new tag.



  4. Next right-click on the Button component and choose Configure Events. 
  5. On the Event Configuration screen, select Mouse Events > onClick.
  6. Click the Add  icon and select Scan Barcode action.



  7. Click OK.  Next we need to set up a Session Event so that Perspective knows how to interpret the scanned barcode data.
  8. Under the Project tab, select Session Events.



  9. On the Session Events screen, select the Barcode Scanned  icon. 

  10. Add the following script to the page:

    system.tag.writeAsync(['[default]New Tag 5'], [data.text])

    We used the tag created for this example, New Tag 5. You can enter your own Tag name if different.




  11. Click OK and save your project.

Test the Example

To test the example, open the Perspective App on your mobile device and load the project. 

  1. Click the Scan Barcode button.



  2. If this is the first time scanning a barcode, you'll get a message requesting permission for Perspective to take pictures and record.



  3. Click Allow.

  4. You can now use the camera on the mobile device to scan the barcode.



  5. Ignition scans the barcode. Once it recognizes the bar code, the script will run and the text is written to the Tag. The label then shows the new Tag value.

IULocgo

Barcode Scanned


The following feature is new in Ignition version 8.0.5
Click here to check out the other new features

Bluetooth Data Received

The Bluetooth Data Received event is only used when a session is running in a native application and it has received bluetooth advertising data. This session event script sends Bluetooth advertising data to Perspective. It supports iBeacon and Eddystone formats.

  • Eddystone will work on iOS and Android
  • iBeacon on iOS requires user to specify the specific region (iBeacon UUID) located on session props bluetooth.config.iBeaconRegion.

Bluetooth "Advertising Data" is the name of the communication data according to the Bluetooth spec. There is no connection to advertising as an industry.

ArgumentsDescription
sessionAn object that references the Project Session
data

List of buffered advertising data. The data comes in as a data object, which has various parts. The following is example output.

{
	"values":
		[
			{
				"rssi":-48,
				"timestamp":1570147485167,
				"manufacturerData":{
					"companyId":6,
					"dataBase64Encoded":"AQkgAl_edccdnHClMvecMCiM--aAkLHAPibd"
				}
			},
			{
				"rssi":-48,
				"timestamp":1570147486012,
				"serviceUUIDs":[
					"FEAA"
					],
				"serviceData":{
					"uuid":"FEAA",
					"dataBase64Encoded":"AOyqqqqqqqqqqqqqAAAAAAAA"
					},
				"eddystoneUID":{
					"txPower":-20,
					"namespaceID":"AAAAAAAAAAAAAAAAAAAA",
					"instanceID":"000000000000"
					}
			},
			{
				"rssi":-54,
				"timestamp":1570147485919,
				"manufacturerData":{
					"companyId":76,
					"dataBase64Encoded":"AhV88isfQjVLY4VnXXfYqpTyAAAAAL8="
					},
				"iBeacon":{
					"uuid":"7CF22B1F-4235-4B63-8567-5D77D8AA94F2",
					"major":0,
					"minor":0,
					"txPower":-65
					}
			},
			{
				"rssi":-54,
				"timestamp":1570147485987,
				"manufacturerData":{
					"companyId":65535,
					"dataBase64Encoded":"vqwSNFZ4EjQSNBI0EjRWeJASAAAAAOwA"
					},
				"AltBeacon":{
					"manufacturerId":65535,
					"uuid":"12345678-1234-1234-1234-123456789012",
					"instance":"00000000",
					"txPower":-20,
					"manufacturerReserved":"00"
					}
			}
	]
}


Accelerometer Data Received

The Accelerometer Data Received event is only used when data is coming in from a batched Accelerometer Action.

ArgumentsDescription
sessionAn object that references the Project Session that called the Accelerometer Data Received event. Use this to identify the specific session that triggered the batching of accelerometer data.
data

The data returned from the batched accelerometer. The data comes in as a data object, which has various parts. Access the various parts like:

logger = system.util.logger('accelerometer')
for row in data.values.data:
	logger.info('X:' + str(row['x']))
	logger.info('Y:' + str(row['y']))
	logger.info('Z:' + str(row['z']))
contextThe user defined context object that can be defined on the action.

Accelerometer Data Received Example

This example will write accelerometer data to the Gateway logs.

  1. For this example, put a Button component onto a view. 
  2. Next right-click on the Button component and choose Configure Events.
  3. On the Event Configuration screen, select Mouse Events > onClick.
  4. Click the Add  icon and select Accelerometer action.
    1. Select Batch mode.
    2. Set a Sample Rate of 400.
    3. Set a Duration of 2000.



  5. Click OK.  Next we need to set up a Session Event so that Perspective knows how to interpret the accelerometer data.
  6. Under the Project tab, select Session Events.



  7. On the Session Events screen, click the Accelerometer Data Received  icon.
     

  8. Add the following script to the page: 

    # This script will take the accelerometer data and print it to the Gateway logs.

# Create the logger.
logger = system.util.logger('accelerometer')

# Loop through the list of batched events and pull out the x, y, and z values to print to the Gateway logs.
for row in data.values.data:
	logger.info('X:' + str(row['x']) + ', Y:' + str(row['y']) + ', Z:' + str(row['z']))
  9. Click OK.
  10. Save your project.

Test the Example

To test the example, open the Perspective App on your mobile device and load the project. 

  1. Click the Accelerometer button.
  2. After clicking the button, the script will record accelerometer data for the next two seconds, so try moving the phone around.
  3. After the two seconds, you should see the logged information appear in the Gateway logs.


IULocgo

Accelerometer Data Received


NFC Ndef Scanned

The NFC Ndef Scanned event is used when the NFC Action is used and the mobile device scans an NFC Tag.

ArgumentsDescription
sessionAn object that references the Project Session that called the NFC Ndef Scanned event. Use this to identify the specific session that scanned the NFC Tag.
data

The data returned from the NFC Tag scan. The data object is a list which can contain multiple records from a single NFC tag. Access the underlying NFC data using:

logger = system.util.logger('NFC')
for row in data:
	logger.info('Type:' + str(row['type']))
	logger.info('Type Name Format:' + str(row['typeNameFormat']))
	logger.info('Payload:' + str(row['payload']))
	logger.info('String:' + str(row['string']))
	logger.info('Bytes:' + str(row['bytes']))
contextThe user defined context object associated with the NFC scan event.

NFC Ndef Scanned Example

This example will write the NFC Tag data to the Gateway logs.

  1. For this example, put a Button component onto a view. 
  2. Next right-click on the Button component and choose Configure Events.
  3. On the Event Configuration screen, select Mouse Events > onClick.
  4. Click the Add  icon and select Scan Ndef NFC action.
  5. Select Single mode, then click OK. 



  6. Next we need to set up a Session Event so that Perspective knows how to interpret the NFC data. Under the Project tab, select Session Events.



  7. On the Session Events screen, click the NFC Ndef Scanned  icon. 



  8. Add the following script to the page: 

    # This script will take the NFC data and print it to the Gateway logs.

# Create the logger.
logger = system.util.logger('NFC')

# Loop through the list of records stored in the NFC tag and pull out the type, type name format, payload, string data, and raw byte data from each record and print it to the Gateway logs.
for row in data:
	logger.info('Type:' + str(row['type']) + ', Type Name Format:' + str(row['typeNameFormat']) + ', Payload:' + str(row['payload']) + ', String:' + str(row['string']) + ', Bytes:' + str(row['bytes']))
  9. Click OK.
  10. Save your project.

Test the Example

To test the example, open the Perspective App on your mobile device and load the project. 

  1. Click the NFC button.
  2. After clicking the button, the script will pass the next NFC tag scanned to the script to be handled.
  3. After scanning an NFC tag, you should see the logged information appear in the Gateway logs.

IULocgo

NFC Ndef Scanned



The following feature is new in Ignition version 8.0.7
Click here to check out the other new features

Message

The Message Handler scripts will run whenever the session receives a message from system.util.sendMessage or system.util.sendRequest. Note that these types of message handlers are different than component-based message handlers, which are accessed with system.perspective.sendMessage. Session Message Handlers can not be called by system.perspective.sendMessage.

ArgumentsDescription
sessionThe Perspective Session that is handling this message.
payload

A dictionary that holds the objects passed to this message handler.
Retrieve them with a subscript, e.g., myObject = payload['argumentName']


  • No labels