EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 1 Table of Contents
Introduction ...... 3 About Terso Solutions ...... 3 Purpose ...... 3 Scope ...... 3 Legal ...... 3 Platform Architecture ...... 4 Jetstream Components ...... 4 Windows Components ...... 4 Windows Environment ...... 5 File System ...... 6 Accounts ...... 6 Permissions ...... 6 Boot Process ...... 7 Runtime Processes ...... 9 Heartbeat Process ...... 9 Command Process ...... 10 Executing Commands ...... 10 Logging Process ...... 11 Dequeue Process ...... 11 Network Process ...... 13 Update Process ...... 13 Shutdown Process ...... 14 LogEntryEvents ...... 14 Parameters ...... 15 DeviceSpecificCommands ...... 16 GetAppConfigValuesCommand ...... 16 SetAppConfigValuesCommand ...... 16 UpdateAppFirmwareCommand ...... 16 Launcher UI ...... 17 Application Software Development ...... 18 Tools ...... 18 Distribution ...... 18 UserApp Event Log ...... 18 Inter-process Communication ...... 18 GetAppParametersCommand...... 18 SetAppParametersCommand ...... 19
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 2 Introduction
About Terso Solutions Terso Solutions, Inc. provides automated inventory management solutions for tracking high-value medical and scientific products in healthcare and life science. Backed by 13 years of RFID product development and implementation experience, our commercially proven, field tested solution has logged over 9,000,000 operational hours around the world. Our integrated RFID solutions can help eliminate manual processes, improve regulatory compliance, and reduce stock-outs and expired products. For more information, visit http://www.tersosolutions.com.
Purpose This document describes the Terso Solution’s kiosk device and a high-level architecture of an application execution environment. It is intended for software developers designing custom application software to run on the Kiosk device and managed through the Terso Solution’s Jetstream platform.
Scope This document describes at a high level the kiosk application execution environment as well as the management of the kiosk device through the Jetstream platform. This document does not describe the kiosk hardware.
Legal Jetstream® and Terso Solutions® are registered trademarks of Terso Solutions, Inc. Please visit https://www.jetstreamrfid.com/legal for more information.
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 3 Platform Architecture
Jetstream Components
Updater.exe
Launcher.exe
Terso Solutions Component App.exe
Custom Application
Figure 1 Components
Component that updates the launcher.exe by executing the logic in the Update Updater.exe Process section.
Component that replaces the window shell to control flow and sandboxes the custom application (app.exe). This component also interfaces with Jetstream to send any Launcher.exe required device management messages as well as poll for new commands that have been queued for the device.
Custom component that has been created by the independent software developer App.exe and is managed by the launcher.exe. This component can be any Windows based application named app.exe.
Windows Components The Windows Embedded 7 image is designed to have a small footprint while balancing features and security. The list below are the feature packs that are included in the image.
.NET Framework Application Support Framework 2.0 COM OLE Support Framework 3.0 COM+ Support Framework 3.5 Win32 Runtimes and Libraries Framework 4.0 Framework 4.5.1
Boot Environment Diagnostics Enhanced Write Filter Common Diagnostic Tools
Data Access and Storage Data Integrity Windows Data Access Components Shadow Copy Volume Interface
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 4 Devices and Printers Internet Explorer 8 Device Framework Engine and Display Driver Frameworks Foundation Standard Windows USB Stack
Graphics and Multimedia Fonts Audio and Video Engines and Media Foundation Bitmap Fonts DirectX and Windows Device Experience TrueType Fonts Graphics Platform Western Fonts Windows Media Player 12 Western Supplemental Fonts
Embedded Enabling Features Management Custom Logon Background Images Power Management Unbranded Startup Screens Microsoft Management Console File Based Write Filter System Management Administrative Tools Hide Boot Screens System Management Utilities Message Box Default Reply Windows Management Instrumentation Windows Update Standalone Installer
Networking User Interface Extensible Authentication Protocol Accessibility Internet Authentication Service Command Prompt Shell with Custom Shell Networking Base Support Networking Foundation Search Indexing Bluetooth Tablet PC Support IRDA and UNIMODEM Text Services Framework Quality of Service Shell Controls and UI Support Functions Remote Access Service Shell Foundation Telephony API Client Windows Firewall
Codecs Security Microsoft AC3 Encoder Active Directory Rights Management Microsoft MPEG-2, ACC Audio Decoder Security Base Microsoft MPEG-2, H.264 Video Decoder MP3 Audio Codecs MPEG-4 Decoders Windows Media Video Codecs, VC-1
System Services Internet Information Services Windows Installer Windows Process Activation Service
Windows Environment Power Configuration: Set to not allow monitor to turn off. Standard power profile in use.
Windows Firewall: Enabled with implicit ALLOW for outbound and DENY for inbound.
Windows Installer: Version 5.0.7601.17514
Windows Media Player: Context menu items removed. Network service set to disabled. Auto update set to disabled.
Windows Shell: Ctrl+Alt+Del options removed from screen.
File Based Write Filter: Service is enabled with an exception for c:\userapp directory and Windows registry files.
Domain/Group Policy: Adding the kiosk to a domain is not supported. No group policy applications or settings can be applied. EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 5 File System Path Description
c:\userapp\ Directory for custom application
c:\program files\terso solutions\updater Directory for the updater.exe application
c:\program files\terso solutions\launcher Directory for the launcher.exe application
c:\program files\terso solutions\bak\ Directory for holding the backup msi files
Accounts User Account Description
TersoKiosk User with limited access rights and is used to execute the app.exe application.
User with elevated access rights and is used to run the launcher.exe and TersoAdmin updater.exe processes.
Permissions Resource TersoKiosk TersoAdmin
userapp directory Read, Write, Modify Full Control
updater directory Read Only Full Control
launcher directory Read Only Full Control
Registry Read Full Control
Add/Remove programs No Access Full Control
Sockets Full Control Full Control
Network Settings Read Only Full Control
System Clock Read Only Full Control
Non-System Directories Read Only Full Control
Event Log Read, Write UserApp Full Control
.net Framework configuration Write to machine.config Full Control
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 6 Boot Process The boot process validates the basic configuration of the Kiosk for operation on the Jetstream platform. The boot process will try to auto launch the app.exe process as well as all the Jetstream management processes. The boot process is divided into two main parts: Network Boot and Process Boot. The Network Boot part is tasked with obtaining a valid connection to the Jetstream platform. The Process Boot part is tasked with starting all Jetstream background processes as well as the app.exe process and finally going into its running state.
Windows Boot
Get Jetstream Connection Info Network Boot
Initialize Network
Initialize Jetstream Processes
Process Boot Launch app.exe
Begin Runtime Loop
Figure 2 Boot Process
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 7 Queue Restarting Initialize Event Queue Command Windows Boot Setup EventLog LogEntryEvent from an Yes Queue CompletionEvent Startup update?
No
Restarting Queue Command Yes from a Reset CompletionEvent Command?
No
Jetstream™ settings No Show Launcher configured?
Yes
Apply launcher.exe network settings
Network Process Boot Yes No Show Launcher Available?
Figure 3 Network Boot
Start Heartbeat Start Command Start Logging Start Dequeue Start Network Network Boot Sync DateTime Start app.exe Process Process Process Process Process
Start app.exe Runtime Health Process
Figure 4 Process Boot
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 8 Runtime Processes
Heartbeat Process To facilitate remote health monitoring of the kiosk, launcher.exe queues a HeartbeatEvent message periodically. The HeartbeatEvent is queued regardless of the current internet connection state. The time to wait between HeartbeatEvents being queued is controlled by the HeartbeatEventInterval parameter.
Start Process
End Process Yes Shutdown? Sleep
No No Yes
Queue Sleep time > 0? HeartbeatEvent
Calculate Sleep Time
Figure 5 Heartbeat Process
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 9 Command Process The command process polls the Jetstream Device Web Server for any commands that need to be executed by the kiosk. The time to wait between polls is controlled by the CommandPollInterval parameter.
Start Process
End Process Yes Shutdown? Sleep
No No Yes
Poll Jetstream Sleep time > 0?
Calculate Command(s)? No Sleep Time
Yes
Execute Commands
Figure 6 Command Process
Executing Commands The launcher.exe process will execute each command in the sequence they were returned from the Jetstream Device Web Server. Once the command has been executed, the launcher.exe process will create and queue a CommandCompletionEvent with results and the CommandId of the command that was executed. Failure to execute one command should not stop execution of the others. The execution of all commands, except the GetAppParameters and SetAppParameters commands, will be executed by the launcher.exe process.
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 10 Logging Process The logging process reads any new event log entries then formats and sends the event log message to Jetstream as a LogEntryEvent. The process will filter out and not send any message that is less than the currently configured LogEntryLevel or is in the LogEntryBlackList. Event Log messages that are larger than the 512 character length limit will be split. Multiple LogEntry elements will be created in the same LogEntryEvent.
End Yes
No
Level > New Event Log Category in Split Message Queue LogEntry Yes No End Entry Blacklist? into N LogEntry LogEntryEvent Level?
Figure 7 Logging Process
Dequeue Process The dequeue process is used to dequeue messages and send them to Jetstream. This process creates a separation of message generation and message queuing and sending. By doing this, other processes can be coded the same regardless if the device is offline or online.
Start Process
End Process Yes Shutdown? Sleep
No Yes
No Sleep time > 0?
WAN Calculate No Available? Sleep Time
Yes Send Process
Figure 8 Dequeue Process
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 11 Start Process
Erase End Process No Messages? message from disk
Yes
Peek 1st Dequeue message message
Yes
Send message to HTTP 200? Jetstream No
Yes No
Increment HTTP Retry < 10 Retry 500 or 404?
No
Queue HTTP 400 Yes LogEntryEvent “InvalidMessage”
No
Write message to EventLog as HTTP Yes “Authentication 401? Failure”
Figure 9 Send Process
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 12 Network Process The launcher.exe process will monitor the current networking state including the internet gateway. Upon determining there is a network state change or gateway outage, the launcher will try to re-establish the network link and gateway.
Write Local Network Apply Network Restart Network Start No EventLog End Available? Settings Interfaces NetworkDown
Yes
End
Figure 10 Network Process
Update Process The update process allows the launcher.exe component to be updated. An UpdateFirmwareCommand will be scheduled in Jetstream with a component type of Agent and a URL pointing to a download location for the Windows Installer msi. The launcher.exe component will receive the command in the GetCommands process and then start the updater.exe program.
Launcher.exe Updater Restart calls Download UpdateFirmware downloads the No Launcher.exe updater.exe Successful? msi with a failure with msi path
Yes
Kill Updater.exe Updater.exe Launcher.exe uninstalls all Process exits installs new and app.exe launcher.exe with 0? Yes launcher.exe processes installs
Overwrite Install factory Install backup Delete new backup Process exits Uninstall new refresh No launcher.exe launcher.exe No launcher.exe with 0? launcher.exe launcher.msi msi install msi with new installer Yes
Start Start launcher.exe launcher.exe with a failure with success code code
End End
Figure 11 Update Process
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 13 Shutdown Process The shutdown process is executed when the launcher.exe is shutdown.
Stop Jetstream Shutdown End processes
Figure 12 Shutdown Process
LogEntryEvents Name Description
Startup Generated when the launcher.exe process is started
AppExeRestart Generated when the launcher.exe process has to restart the app.exe process
AppExeDown Generated when the launcher.exe process cannot start the app.exe process
FirmwareInfo Generated daily indicating the software version of launcher.exe
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 14 Parameters Name Description Type Unit Default
The accesskey required String AccessKey by Jetstream for each GUID NA (36 chars) request from the device.
The product GUID for the app msi. Setting cannot String AppMSIGuid GUID NA be set or retrieved using (36 chars) Jetstream.
Time to wait between Int CommandPollInterval polling for new Minute 60 (0-60) commands.
DNS address to use in a String DNS NA 0.0.0.0 non–DHCP LAN. (0-255)*4
Gateway address to use String Gateway NA 0.0.0.0 in a non-DHCP LAN. (0-255)*4
The time to wait between sending a HeartbeatEvent Int HeartbeatEventInterval to Jetstream. A setting of Minute 60 (0-60) 0 will disable HeartbeatEvents.
IP address to use in a String IP NA 0.0.0.0 non-DHCP LAN. (0-255)*4
us- Base web address for JetstreamDeviceUrl String URL device.tersosolutions.c Jetstream. om
The product GUID for the String f6e18148-dfb2-4c2d- LauncherGUID launcher msi. Not get/set GUID (36 chars) 9ee5-cfecfb5ec688 able from Jetstream.
A comma separated list of event log categories to Defrag, LogEntryBlackList String NA black list from being sent KioskLauncherLocal to Jetstream.
String Off Error The level of logging that Warning LogEntryLevel the Agent should send to NA Error Information Jetstream. Verbose Trace Debug
The password used for String MaintenancePassword accessing maintenance NA [Omitted] (15 chars) functions.
Subnet mask to use in a Int Subnet NA 0.0.0.0 non-DHCP LAN. (0-255)*4
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 15 DeviceSpecificCommands
GetAppConfigValuesCommand GetAppConfigValuesCommand allows an application to get its configuration values through Jetstream. The launcher.exe process will use inter-process communications to send the requested configuration parameter names to the app.exe process. The app.exe process should then query its own configuration and return the current values of the parameters requested. Once the configuration values are returned from the app.exe process they are returned to Jetstream in the appropriate CommandCompletionEvent by the launcher.
Query String Parameters
Parameters – An underscore (_) delimited list of configuration parameter names to get.
SetAppConfigValuesCommand SetAppConfigValuesCommand allows an application to set its configuration values through Jetstream. The launcher.exe process will use inter-process communications to send the configuration parameter name and value to be set to the app.exe process. The app.exe process should then update its own configuration and then return the result of the update.
Query String Parameters
Add the configuration name-value pairs as query string parameters to set them. For example, if a configuration parameter named XYZTimeout exists, to set the value to 60, add a query string parameter of XYZTimeout=60 to the Jetstream DeviceSpecificCommand URL.
UpdateAppFirmwareCommand The UpdateAppFirmwareCommand allows an application to update its application code on the kiosk remotely through Jetstream. When the launcher receives an UpdateAppFirmwareCommand from Jetstream, it will download the installer from the URL parameter and pass the username and password as HTTP basic authentication headers. Then it will use the Windows Installer framework’s msiexec.exe command line tool to run the installer.
Query String Parameters
URL – The HTTP URL of the Windows Installer file
Username – The optional HTTP basic authentication username to use
Password – The optional HTTP basic authentication password to use
Windows Installer Requirements
Optimize for size Use the RemovePreviousVersions bit and keep the UpgradeCode the same to cleanup previous installs Update all .NET assembly file versions to match the version attribute in the installer
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 16 Launcher UI The launcher.exe UI is displayed when there is not enough information to progress past the network boot section of the boot process or if the user initiated the app.exe escape key command.
The launcher will display the current DeviceSerialNumber and network information as well as options for the user to configure the system.
Example:
Terso Solution’s Kiosk Launcher ------DeviceSerialNumber: ABC123 IP: 123.123.123.6 Subnet: 255.255.255.0 DNS: 123.123.123.1 Gateway: 123.123.123.1 JetstreamDeviceUrl https://us-devicebeta.tersosolutions.com/device JetstreamAccessKey 2181a7ba-b463-44f0-ab16-c1cb3f0a546f
Network IP: 192.168.0.75 Subnet: 255.255.255.0 DNS: 192.168.0.1 Gateway: 192.168.0.1
Options 1. Set Network Settings 2. Set Jetstream Settings 3. Logoff
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 17 Application Software Development
Tools Required tools for building a Kiosk application:
Visual Studio 2010 (.net) or Eclipse (Java) Windows Installer packager Internet accessible HTTP server for hosting the app.exe installer packages Application and installer must be built as 32-bit applications; 64-bit is not supported
Distribution 1.) Create an application called app.exe 2.) Package the application into a Windows Installer file (msi) 3.) Upload the Windows Installer file to an internet facing HTTP server 4.) Schedule a Jetstream DeviceSpecificCommand – UpdateAppFirmware with the HTTP URL to the Windows Installer 5.) Validate the result of the DeviceSpecificCommand – UpdateAppFirmware by viewing the associated CommandCompletionEvent
UserApp Event Log Your application may log events to the Microsoft Windows event log using a source of UserApp. The app.exe process has full write privileges to the UserApp source. Any events with a source of UserApp will also be sent to Jetstream following the normal LogEntryLevel and LogEntryBlackList rules.
Inter-process Communication Inter-process communication between the launcher.exe process and the app.exe process will be done through the use of TCP sockets. The app.exe process should listen for communications on the local loop on port 8000. Application messaging will use HTTP and POST messages to various endpoints.
GetAppParametersCommand The GetAppParametersCommand is a command that requests the current values for the application parameters. The application should query the current values for the parameters requested and return them in a GetAppParametersCommandResponse message.
URL: http://127.0.0.1:8000/GetAppParametersCommand
Example Request:
Example Response:
SetAppParametersCommand The SetAppParametersCommand is a command that requests the application set the current running parameter values to a new value. The application should validate that the new value is valid from both a data type and logical perspective; e.g., the application should return an exception if the request says to change a poll rate to a negative number.
URL: http://127.0.0.1:8000/SetAppParametersCommand
Example Request:
Example Response:
EDOC00054 - Jetstream Kiosk Developers Guide, rev 1 19