Presence

Hobson defines the concept of presence as an entity (e.g. person) entering or exiting a location. This capability facilitates creating Hobson tasks that can execute as people move around. All presence-related functions are accessible through the Hobson REST API.

Entities

As mentioned above, an entity is a "something" that can enter and exit locations. In most cases this will be determined by the location of their mobile device but other means of tracking entities could potentially exist (e.g. RFID). Note that the generic term "entity" (rather then "person") is used by the API so the concept can include things other than people (e.g. vehicles, medical devices, etc.)

Creating an entity

Adding a new presence entity is done with the following API call:

http://hobson-automation.com/apidoc/#api-Presence-AddPresenceEntity

The API call requires a human-readable name for the new entity and it will be auto-assigned a unique identifier by the API.

Locations

A location is a geographic area that an entity can enter or exit. There are two categories of locations – map (geofence) and beacon (Bluetooth LE).

Map locations

Map locations are defined by a geofence – latitude, longitude and radius (in feet). This type of location is useful when a high degree of precision is not needed. For example, tracking when a user arrives or departs from their home would make sense as a map location.

Beacon locations

Beacon locations are defined by a major and minor ID associated with a Bluetooth LE beacon hardware device. This type of location is useful when a high degree of precision is needed. For example, tracking when a user enters a particular room in a house would make sense as a beacon location.

Creating a location

Adding a new presence location is done with the following API call:

http://hobson-automation.com/apidoc/#api-Presence-AddPresenceLocation

The API call takes either latitude/longitude/radius or beacon major/minor attributes (but not both).

Updating an entity's location

Hobson will maintain the current location of presence entities. As that value changes, events are fired that will allow tasks to run. For example, a task could be defined that turns on outside lights when one or more people arrive home.

Updating the location of presence entity is done with the following API call:

http://hobson-automation.com/apidoc/#api-Presence-UpdatePresenceEntity

Usage Example

This capability is most easily implemented in mobile application using the operating system's geofencing and Bluetooth beacon APIs. For example, iOS provides these functions through its Core Location API. On Android, the service location APIs are provided.

A pattern of usage for a mobile application to leverage the Hobson presence capabilities might be:

1. Within the mobile application, ask the user which Hobson presence entity they are associated with. You can enumerate the presence entities defined in Hobson via the following API call: http://hobson-automation.com/apidoc/#api-Presence-GetAllPresenceEntities
   
   
2. Once the user has identified their presence entity, the mobile application asks Hobson for a list of all presence locations that have been defined via the following API call: http://hobson-automation.com/apidoc/#api-Presence-GetAllPresenceLocations. With that information, the mobile application should use the appropriate iOS or Android API to create the geofences and/or beacon callbacks. Note that the list of Hobson presence locations should be periodically checked as users may add or remove them.
   
   
3. When the mobile application receives an operating system callback from a geofence or beacon, it should call the Hobson "update presence entity" API resource (as mentioned above) to update the presence entity location.