Configure geofencing

Geofencing is a mechanism to create a virtual perimeter that allows you configure your IX15 device to perform actions when entering or exiting the perimeter. For example, you can configure a device to factory default if its location service indicates that it has been moved outside of the geofence.

Multiple geofences can be defined for one device, allowing for a complex configuration in which different actions are taken depending on the physical location of the device.

Required configuration items

Location services must be enabled.
The geofence must be enabled.
The boundary type of the geofence, either circular or polygonal.
- If boundary type is circular, the latitude and longitude of the center point of the circle, and the radius.
- If boundary type is polygonal, the latitude and longitude of the polygon's vertices (a vertex is the point at which two sides of a polygon meet). Three vertices will create a triangular polygon; four will create a square, etc. Complex polygons can be defined.
Actions that will be taken when the device's location triggers a geofence event. You can define actions for two types of events:
- Actions taken when the device enters the boundary of the geofence, or is inside the boundary when the device boots.
- Actions taken when the device exits the boundary of the geofence, or is outside the boundary when the device boots.
For each event type:
- Determine if the action(s) associated with the event type should be performed when the device boots inside or outside of the geofence boundary.
- The number of update intervals that should take place before the action(s) are taken.
Multiple actions can be configured for each type of event. For each action:
- The type of action, either a factory erase or executing a custom script.
- If a custom script is used:
  - The script that will be executed.
  - Whether to log output and errors from the script.
  - The maximum memory that the script will have available.
  - Whether the script should be executed within a sandbox that will prevent the script from affecting the system itself.

Additional configuration items

Update interval, which determines the amount of time that the geofence should wait between polling for updated location data.

 Command line

Select the device in Remote Manager and click Actions > Open Console, or log into the IX15 local command line as a user with full Admin access rights.
Depending on your device configuration, you may be presented with an Access selection menu. Type admin to access the Admin CLI.
At the command line, type config to enter configuration mode:
```
> config
(config)>
```

Add a geofence:

(config)> add service location geofence name
(config service location geofence name)>

where name is a name for the geofence. For example:

(config)> add service location geofence test_geofence
(config service location geofence test_geofence)>

The geofence is enabled by default. To disable:

(config service location geofence test_geofence)> enable false
(config service location geofence test_geofence)>

Set the amount of time that the geofence should wait between polling for updated location data:
```
(config service location geofence test_geofence)> update_interval value
(config service location geofence test_geofence)>
```
where value is any number of weeks, days, hours, minutes, or seconds, and takes the format number{w|d|h|m|s}.
For example, to set update_interval to ten minutes, enter either 10m or 600s:
```
(config service location geofence test_geofence)> update_interval 600s
(config service location geofence test_geofence)> 
```
The default is 1m (one minute).

Set the boundary type for the geofence:

(config service location geofence test_geofence)> boundary value
(config service location geofence test_geofence)>

where value is either circular or polygonal.

If boundary is set to circular :
1. Set the latitude and longitude of the center point of the circle:
```
(config service location geofence test_geofence)> center latitude int
(config service location geofence test_geofence)> center longitude int
(config service location geofence test_geofence)> 
```
  where int is:
  - For latitude, any integer between -90 and 90, with up to six decimal places.
  - For longitude, any integer between -180 and 180, with up to six decimal places.
2. Set the radius of the circle:
```
(config service location geofence test_geofence)> radius radius
(config service location geofence test_geofence)> 
```
  where radius is an integer followed by m or km, for example, 100m or 1km.

If boundary is set to polygonal:

Set the coordinates of one vertex of the polygon. A vertex is the point at which two sides of a polygon meet.

Add a vertex:

(config service location geofence test_geofence)> add coordinates end
(config service location geofence test_geofence coordinates 0)>

Set the latitude and longitude of the vertex:

(config service location geofence test_geofence coordinates 0)> latitude int
(config service location geofence test_geofence coordinates 0)> longitude int
(config service location geofence test_geofence coordinates 0)>

where int is:

For latitude, any integer between -90 and 90, with up to six decimal places.
For longitude, any integer between -180 and 180, with up to six decimal places.

Configure additional vortices:

(config service location geofence test_geofence coordinates 0)> ..
(config service location geofence test_geofence coordinates)> add end
(config service location geofence test_geofence coordinates 1)> latitude int
(config service location geofence test_geofence coordinates 1)> longitude int
(config service location geofence test_geofence coordinates 1)>

where int is:

For latitude, any integer between -90 and 90, with up to six decimal places.
For longitude, any integer between -180 and 180, with up to six decimal places.

Repeat for each vortex of the polygon.

Define actions to be taken when the device's location triggers a geofence event:
- To define actions that will be taken when the device enters the geofence, or is inside the geofence when it boots:
  1. (Optional) Configure the device to preform the actions if the device is inside the geofence when it boots:
    (config)> service location geofence test_geofence on_entry bootup true (config)>
  2. Set the number of update_intervals that must take place prior to performing the actions:
    (config)> service location geofence test_geofence on_entry num_intervals int (config)>
    For example, if the update interval is 1m (one minute) and the num_intervals is set to 3, the actions will not be performed until the device has been inside the geofence for three minutes.
  3. Add an action:
    Type ... to return to the root of the configuration:
    (config service location geofence test_geofence coordinates 3)> ... (config)>
    Add the action:
    (config)> add service location geofence test_geofence on_entry action end (config service location geofence test_geofence on_entry action 0)>
  4. Set the type of action:
    (config service location geofence test_geofence on_entry action 0)> type value (config service location geofence test_geofence on_entry action 0)>
    where value is either:
    factory_erase—Erases the device configuration when the action is triggered.
    script—Executes a custom script when the action is triggered.
    factory_erase or script.
    If type is set to script:
    Type or paste the script, closed in quote marks:
    (config service location geofence test_geofence on_entry action 0)> commands "script" (config service location geofence test_geofence on_entry action 0)>
    If the script begins with #!, then the proceeding file path will be used to invoke the script interpreter. If not, then the default shell will be used.
    To log the output of the script to the system log:
    (config service location geofence test_geofence on_entry action 0)> syslog_stdout true (config service location geofence test_geofence on_entry action 0)>
    To log the errors from the script to the system log:
    (config service location geofence test_geofence on_entry action 0)> syslog_stderr true (config service location geofence test_geofence on_entry action 0)>
    (Optional) Set the maximum amount of system memory that will be available for the script and it spawned processes:
    (config service location geofence test_geofence on_entry action 0)> max_memory value (config service location geofence test_geofence on_entry action 0)>
    where value is any integer followed by one of the following: b|bytes|KB|k|MB|M|GB|G|TB|T.
    For example. the allocate one megabyte of memory to the script and its spawned processes:
    (config service location geofence test_geofence on_entry action 0)> max_memory 1MB (config service location geofence test_geofence on_entry action 0)>
    A sandbox is enabled by default to prevent the script from adversely affecting the system. To disable the sandbox:
    (config service location geofence test_geofence on_entry action 0)> sandbox false (config service location geofence test_geofence on_entry action 0)>
    If you disable the sandbox, the script may render the system unusable.
    Repeat for any additional actions.
- To define actions that will be taken when the device exits the geofence, or is outside the geofence when it boots:
  1. (Optional) Configure the device to preform the actions if the device is outside the geofence when it boots:
    (config)> service location geofence test_geofence on_exit bootup true (config)>
  2. Set the number of update_intervals that must take place prior to performing the actions:
    (config)> service location geofence test_geofence on_exit num_intervals int (config)>
    For example, if the update interval is 1m (one minute) and the num_intervals is set to 3, the actions will not be performed until the device has been outside the geofence for three minutes.
  3. Add an action:
    Type ... to return to the root of the configuration:
    (config service location geofence test_geofence coordinates 3)> ... (config)>
    Add the action:
    (config)> add service location geofence test_geofence on_exit action end (config service location geofence test_geofence on_exit action 0)>
  4. Set the type of action:
    (config service location geofence test_geofence on_exit action 0)> type value (config service location geofence test_geofence on_exit action 0)>
    where value is either:
    factory_erase—Erases the device configuration when the action is triggered.
    script—Executes a custom script when the action is triggered.
    factory_erase or script.
    If type is set to script:
    Type or paste the script, closed in quote marks:
    (config service location geofence test_geofence on_exit action 0)> commands "script" (config service location geofence test_geofence on_exit action 0)>
    If the script begins with #!, then the proceeding file path will be used to invoke the script interpreter. If not, then the default shell will be used.
    To log the output of the script to the system log:
    (config service location geofence test_geofence on_exit action 0)> syslog_stdout true (config service location geofence test_geofence on_exit action 0)>
    To log the errors from the script to the system log:
    (config service location geofence test_geofence on_exit action 0)> syslog_stderr true (config service location geofence test_geofence on_exit action 0)>
    (Optional) Set the maximum amount of system memory that will be available for the script and it spawned processes:
    (config service location geofence test_geofence on_exit action 0)> max_memory value (config service location geofence test_geofence on_exit action 0)>
    where value is any integer followed by one of the following: b|bytes|KB|k|MB|M|GB|G|TB|T.
    For example. the allocate one megabyte of memory to the script and its spawned processes:
    (config service location geofence test_geofence on_exit action 0)> max_memory 1MB (config service location geofence test_geofence on_exit action 0)>
    A sandbox is enabled by default to prevent the script from adversely affecting the system. To disable the sandbox:
    (config service location geofence test_geofence on_exit action 0)> sandbox false (config service location geofence test_geofence on_exit action 0)>
    If you disable the sandbox, the script may render the system unusable.
    Repeat for any additional actions.
Save the configuration and apply the change.
```
(config)> save
Configuration saved.
>
```
Type exit to exit the Admin CLI.
Depending on your device configuration, you may be presented with an Access selection menu. Type quit to disconnect from the device.