added in Milestone 100

gn:act_service

Description

Action is used to initialize a ginstr launcher service, to configure it's parameters or to stop the service.

Always only one instance of service and it's configuration exists.

In order to use the service, a listener has to be attached to it.

Action returns

void

Action signatures

[gn:act_service]|[serviceId;serviceParameters{n}]

Parameter	Description
serviceId	Name of the service which will be used Valid services: nfc, provides nfc features gps, provides gps features qr, provides qr features timer (M2.5.11), executes action set in regular time intervals event (M2.5.13), executes action set on events bleIIoT (M11.0.0), provides IIoT features
serviceParameters{n}	Parameters of service which are configured. Parameters always have the id like "start", "stop", "triggerActionSet", and various amount of properties. The service parameters are separated by ";" while internal properties are separated by ",". Service parameters can also be "global" and "individual". Global service parameters are equal for all listeners which are attached to service and if the service configuration changes they are valid for all the attached listeners while "individual" service parameters are transferred to each listener on time of adding the listener. This enables ginstr app developer to have different configurations per listener i.e. we have 2 listeners we want that widget receives NFC id and we want that variable receives NFC embedded content. nfc service parameters: start (global) starts nfc service it needs to be called before any other service parameters stop (global) stops nfc service and removes all service listeners, removes service configuration nfcReadingsInterval,seconds (global) defines minimum time between two readings in seconds. If scan happens before minimum time dialog box will show to wait triggerActionSet,targetId,actionSetId (individual) defines which action block should be executed after the scan is done, targetId is the widget which holds the action block and actionSetId is the name of the action set that will be executed. Behavior is similar to gn:act_trigger action sourceType,type (individual) defines weather the scan should read the nfc id or nfc embedded content. Possible values for type are: tagId embedded required (global) if set on service it will check if nfc hardware is ready for scanning. If hardware does not exists a popup message will be shown, if hardware is turned off android settings panel for nfc will be open and user can switch it on alertType,type (global) defines if there will bi vibration or sound to alert the user during scan. Possible values for type are: sound vibrate none soundFile,fileNameWithExtension (global) defines if some other sound than default nfc scan sound will be played when alertType is set to sound. fileNameWithExtension needs to be replaced with actual file name and extension and the sound file must be located in assets folder of the ginstr app i.e. "glassPing.mp3" emulatorsAllowed (global) bypasses hardware checks and allows usage of GnNfcEmulator widget writeTag,writeSource,successTargetId,successActionSetId,failTargetId,failActionSetId defines parameters for nfc widget write. If write tag parameters are present upon the scan of nfc tag nfc service will try to write content to nfc tag. writeSource - source from which the value for write to nfc tag will be taken. Allowed sources are of TEXT datatype successTargetId - (optional) callback target where action set will be executed if nfc tag is successfully written. Behavior is similar to gn:act_trigger action successActionSetId - (optional) success write callback action set name on the successTargetId widget failTargetId - (optional) callback target where action set will be executed if nfc tag is not successfully written. Behavior is similar to gn:act_trigger action failActionSetId - (optional) fail write callback action set name on the successTargetId widget password,errorCodesTarget Only supported on NTAG216. When tag is scanned if password is not set it enables password protection. If the "password" parameter is not present in nfc service configuration password if set will be removed during scan. errorCodesTarget returns error codes into @variable target. Possible error codes: success (0) - tag operation succeeded exception (1) - something went wrong invalid password(2) - invalid password was provided to authenticate with the tag no authentication (3) - tag was tampered with, and data might have been compromised read failed (4) - attempt to read data resulted in exception (tag was removed to soon from device,...) write failed (5) - attempt to write data resulted in exception (tag was removed to soon from device, ...) write content too long(6) - content is longer than maximum storage on NFC for write not writeable(7); - it means that the tag is write protected, set to read only mode encryption when tag is scanned if the parameter is present the content that is read from the tag is being decrypted by launchers internal decryption mechanisms. If write writeTag is set and tag is being written with content the content will get encrypted before writing to tag gps service parameters: start (global) starts gps service. It needs to be called before any other service parameters stop (global) stops gps service and removes all service listeners, service parameter configuration is kept mockLocation (global) if mocklocation is enabled it will randomly return one of 11 default mock locations gpsPrecision (global) triggers higher precision readings only to be accepted as results. This might prolong receiving GPS lock. triggerActionSet,targetId,actionSetId (individual) defines which action block should be executed after the scan is done, targetId is the widget which holds the action block and actionSetId is the name of the action set that will be executed. Behavior is similar to gn:act_trigger action showAddress,value (individual) defines weather the address retrieved from nominatim server or coordinates will be set into target when GPS is obtained. Possible value for value is: false configures gps service to show coordinates providers (global) defines a list of active providers separated by comma, e.g. (gps,passive) gps - determines location using satellites. network - determines location based on availability of cell tower and WiFi access points passive - a special location provider for receiving locations without actually initiating a location fix. This provider can be used to passively receive location updates when other applications or services request them without actually requesting the locations yourself. failover (global) defines a failover provider with additional parameters (e.g. failover,gps,5,30000) provider - gps,network,passive noOfRetires - hardcoded value, e.g. 5 timeout - hardcoded value in miliseconds e.g. 30000 disableMinDistanceCheck (global) disables minimum distance gps validation check qr service parameters: (milestone 101) start (global) starts qr service it needs to be called before any other service parameters (stop is always called automatically after the service is executed) autoEnableTorch (global) if autoEnableTorch is set as true it will start the service with device flash turned on. Possible value for value is: true enables torch triggerActionSet,targetId,actionSetId (individual) defines which action block should be executed after the scan is done, targetId is the widget which holds the action block and actionSetId is the name of the action set that will be executed. Behavior is similar to gn:act_trigger action timer service parameters: (M2.5.11) start (global) starts timer service it needs to be called before any other service parameters (stop is always called automatically after the service is executed) interval (global) defines how often the service will be triggered 10000 miliseconds triggerActionSet,targetId,actionSetId (individual) defines which action block should be executed after the scan is done, targetId is the widget which holds the action block and actionSetId is the name of the action set that will be executed. Behavior is similar to gn:act_trigger action event service parameters: (M2.5.13) start (global) starts event service it needs to be called before any other service parameters (stop is always called automatically after the service is executed) onResumeTriggerActionSet,targetId,actionSetId (individual) defines which action block should be executed after the onResume event is fired, targetId is the widget which holds the action block and actionSetId is the name of the action set that will be executed. Behavior is similar to gn:act_trigger action onPauseTriggerActionSet,targetId,actionSetId (individual) defines which action block should be executed after the onPause event is fired, targetId is the widget which holds the action block and actionSetId is the name of the action set that will be executed. Behavior is similar to gn:act_trigger action When the bleIIoT service starts, it will collect IoT devices during the action interval. After the interval pass, all collected IoT devices will be stored into the target(DtRows) and triggerActionSet will be executed. Only one instance of triggerActionSet can be executed at the same time. During triggerActionSet execution, the service will collect iot devices until next triggerActionSet execution. DtRows columns definition: mac (DtText) deviceSerial (DtText) modelId (DtNumber) configHash (DtText) processorId (DtText) rtc (DtNumber) bleIIoT service parameters: (M11.0.0) start (global) starts bleIIoT service. It needs to be called before any other service parameters stop (global) stops bleIIoT service and removes all service listeners, service parameter configuration is kept interval (global) defines how often the service will be triggered 2000 miliseconds triggerActionSet,targetId,actionSetId (individual) defines which action block should be executed after the scan is done, targetId is the widget which holds the action block and actionSetId is the name of the action set that will be executed. Behavior is similar to gn:act_trigger action

Example NFC service

Following nfc example has two nfc service configurations, in both services configuration it has 4 service parameters and to each configuration one service listener is attached. On load of the ginstr launcher screen start a nfc service which has maximum readings interval set to 1 second, alertType is set to vibrate so there will be vibration when scan is done, and when scan is done action set gn:act_set will be exectued on @+id/exampleFrame widget. Finally service listener will be attached with nfc service configuration that was just explained. When first scan is performed nfc service will be reconfigured and new listener will be added. This is just an example of how easy you can control flow with service configuration if required, in normal apps use cases might be much simpler.

hardware nfc data

04C357BA482780 - id

test - embedded

initial contents

@+id/screen_nfc_input widget

@variable/nfc_variable

variables.xml

<variable id="nfc_variable" type="text" defaultValue=""></variable>

screen.xml

<FrameLayout
    android:id="@+id/exampleFrame"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:visibility="gone"
    gn:act_beforeLoad="[gn:act_service]|[nfc;start;triggerActionSet,@+id/exampleFrame,gn:act_set;nfcReadingsInterval,1;alertType,vibrate],[gn:act_addServiceListener]|[nfc;@+id/screen_nfc_input]"
    gn:act_set="[gn:act_service]|[nfc;sourceType,embedded;alertType,sound;soundFile,glassPing.mp3;nfcReadingsInterval,10],[gn:act_addServiceListener]|[nfc;@variable/nfc_variable]" />

 <com.ginstr.widgets.GnEditText
    android:id="@+id/screen_nfc_input"
    android:layout_height="wrap_content"
    android:layout_width="match_parent"
    gn:dataType="text"
    gn:s_sourceType="input"/>

after 2 nfc scans contents

@+id/screen_nfc_input widget 04C357BA482780

@variable/nfc_variable test

---

Example GPS service

Following gps example has two gps providers (gps, passive) in combination with the failover provider. On load of the ginstr launcher screen start a gps service which has defined two providers (network,passive), one failover provider (gps) with additional parameters noOfRetires (5) and timeout (30000 ms) and disableMinDistanceCheck parameter which will disable minimum distance gps validator check. After the service is started, it will try to get coordinate from defined providers; in case there is no valid coordinate for more than 30 seconds or the service receives more than 5 invalid coordinates, the failover provider will be started and it will be active until one valid coordinate is returned. After that, the failover provider is stopped.

initial contents

@+id/Geofence

screen.xml

<RelativeLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:gn="http://schemas.ginstr.com/ginstr"
    android:id="@+id/locationScreen"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    gn:act_beforeLoad="
        [gn:act_service]|[gps;start;providers,network,passive;failover,gps,5,30000;disableMinDistanceCheck],
        [gn:act_addServiceListener]|[gps;@+id/Geofence]">

<com.ginstr.widgets.GnEditText
    android:id="@+id/Geofence"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    gn:s_hint="@string/location_geofenceCenterPointHint"
    gn:style="@style/editableInputStyle"			
    gn:s_sourceType="input"/>

after gps service reading

@+id/Geofence 41.0,10.0

---