iobroker-community-adapters / ioBroker.places

Adapter for ioBroker for analyzing location information
MIT License
5 stars 5 forks source link
gps-location home-automation iobroker places smarthome

Logo

ioBroker.places

Number of Installations Number of Installations NPM version

Test and Release Translation status Downloads

This adapter uses Sentry libraries to automatically report exceptions and code errors to the developers. For more details and for information how to disable the error reporting see Sentry-Plugin Documentation! Sentry reporting is used starting with js-controller 3.0.

Description

This is an ioBroker adapter for processing location information messages which should contain a user, a geo-position and a timestamp as minimum. The adapters analyzes whether the location information is within a radius around the location configuration of ioBroker or optional other places.

Configuration

There is just one mandatory configuration value: the radius (meters) which will be used to identify the current location of a user. The location of ioBroker is used to identify users being "at home", other places can be added as part of the configuration.

Usage

To process location update just send a message using the following syntax:

// send a message to all instances of places adapter
sendTo('places', {
        user:       "Name of person", 
        latitude:   50.9576191, 
        longitude:  6.8272409, 
        timestamp:  1520932471
});

// send a message to a specific instance of places adapter adapter
sendTo('places.0', {
        user:       "Name of person", 
        latitude:   50.9576191, 
        longitude:  6.8272409, 
        timestamp:  1520932471
});

// send a message to a specific instance and define a callback
sendTo('places.0', {
        user:       "Name of person", 
        latitude:   50.9576191, 
        longitude:  6.8272409, 
        timestamp:  1520932471
}, function (res) { log(JSON.stringify(res)); });

Structure for returned messages

The following block shows how response messages look like. For each value the ioBroker object tree has an according state.

{
    "user":         "Name of person",       // name of person (may have been replaced by user mapping)
    "latitude":     50.9576191,
    "longitude":    6.8272409,
    "timestamp":    1520932471000,
    "date":         "2018-03-13 10:14:31",  // date extracted from timestamp
    "atHome":       false,                  // true if inside the configured radius around ioBroker
    "homeDistance": 104898,                 // distance in meters between position and ioBroker
    "name":         "",                     // name of place found within the configuration
    "address":      "",                     // readable address (if geocoding is active)
    "elevation":    "",                     // elevation in meters (if geocoding is active)
}

Sample: OwnTracks + ioBroker.iot + ioBroker.places

1. Configure iobroker.iot

Add a custom services xyz under White list for Services.

2. Configure OwnTracks mobile apps

Change the mode to HTTP Private and use the following address as Host : https://iobroker.pro/service/custom_xyz/

3. Configure iobroker.places

On the tab Integration you have to select the instance of the cloud adapter and xyz as service. The adapter will listen to incoming requests for the service and start the processing.

Sample: Telegram + ioBroker.telegram + ioBroker.places

1. Configure iobroker.telegram

Enable the option to store raw requests.

2. Create script (ioBroker.javascript)

Create a short script with a subscription to the raw request, f.e. from telegram.0.communicate.requestRaw, and send a new request object to iobroker.places (or an instance of it):

on({id: "telegram.0.communicate.requestRaw", change: "ne"}, function (obj) {
    var data = JSON.parse(obj.newState.val);
    if (data.from && data.location) {
        sendTo('places.0', {
            user: data.from.first_name, 
            latitude: data.location.latitude, 
            longitude: data.location.longitude, 
            timestamp: data.date
        }, function (res) { log('places analyzed telegram position as: ' + JSON.stringify(res)); });
    }
});

Credits

The implementation is partly based on dschaedls ioBroker.geofency adapter. The logo has been taken from Free Icons PNG and has been modified to have a transparent background.

Changelog

1.2.0 (2024-04-25)

1.1.2 (2022-04-17)

1.1.1 (2022-03-29)

1.1.0 (2022-03-25)

1.0.0 (2020-08-16)

0.7.0 (2019-01-12)

0.6.2 (2018-12-06)

0.6.1

0.6.0

0.5.1

0.5.0

0.4.2

0.4.1

0.4.0

0.3.0

0.2.3

0.2.2

0.2.1

0.2.0

0.1.1

0.1.0

License

The MIT License (MIT)

Copyright (c) 2023-2024 ioBroker Community Developers iobroker-community-adapters@gmx.de
Copyright (c) 2018-2022 BasGo basgo@gmx.de

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.