Custom Position (P)
What is it?
This device type allows the plug-in to process position data received via an http POST or GET request. See below for the correct URL formatting and accepted parameters.
This type of device can be used when the user has control over the formatting of the request data.
A group of HS3 devices will be created that includes all possible data types.
Add a new Custom Position User/Device Type
From the User / Devices configuration page, select Custom Position (P)
General Options
Device Enabled
Enable / Disable this device.
Device Id
By default the plug-in will assign the HS3 device ref as the DeviceId. This can be changed but should be a unique value amongst position type devices.
Minimum distance to move
This is the minimum distance that a new position update must be from the last known position for it to be considered as new.
Recommended starting value for this field is 0.5 miles or 0.8 kilometres
Ignore new position if accuracy > (metres)
If the reported accuracy of the new position > this value then the position will be ignored. Accuracy is always shown in metres regardless of the units setting.
Recommended starting value for this field is 2000 metres.
Show Address Only
If enabled hyper-links and additional data will not be added to the Street Address device for this user.
Record to Database
If selected, both new position updates will be recorded to the plug-in's database for later viewing / mapping.
Dynamic Mapping Options
Build a New Map when Location Changes
If enabled a new dynamic map of the device's current location will be created whenever its location is updated.
By default the map file will be saved as \HS3\html\PHLocation2\Maps\XXXX_current.html where XXXX is the DeviceId.
Map Icon (Google Only)
This option allows specifying different map marker icons on Google maps only. All other map providers have fixed icons.
Map Marker Character
Choose the character displayed on the dynamic map marker. Valid choices are A to Z or Off.
Initial Map Type
Specifies the map type that is initially set when a map is displayed on the internal map viewer.
Initial Max Zoom Level
On a single point or multi-point map where all points are very close together, the map can sometimes be over-zoomed making it difficult to read.
This options allows setting a max initial zoom level so the map won't open in an over-zoomed state.
Under normal circumstances leave this set at Auto and the plug-in will handle the correct zoom level.
Map Size
Set the size of the map. Max size is 1000 x 1000 px.
Override File Path / Name
By default the auto-generated all users map will be saved to:
\HS3\html\PHLocation2\Maps and the file name will be all_users_current.html
The path and/or file name can be overridden using these settings.
The file name can take replacement variables which must be enclosed between the dollar symbol like $variable$.
You can specify multiple variables together ($YMD$) or singularly ($Y$/$D$/$M$).
Supported variables are
A=Yesterday's date (YYYYMMDD)
Y=Current Year (YYYY)
M=Current Month (MM)
D=Current Day (DD)
h=Current Hour (hh)
m=Current Minute (mm)
s=Current Second (ss)
Include this device on All Users Dynamic Map
If enabled, this device's current location will be included on the all users dynamic map. See here for options relating to the all users map.
Rebuild Child Devices Button
If a child device has been deleted or new features are added in a future plug-in release that require additional child devices, then this function will rebuild any missing child devices and add them to the group.
Base URL
For direct connection to HS3's web server: http://yourhomeseerserver/phl2api?dtype=CD&type=P
NOTE: https is supported if your HS3 web server is configured for https access.
For connection via MyHS: https://connected2.homeseer.com/phl2api?dtype=CD&type=P
NOTE:
Both connection methods require the request to be authenticated. If using the MyHS method then use your MyHS credentials. For a direct connection use a valid HS3 user/pass combination.
A typical complete URL to send a basic position report might look like:
The minimum data required for a location to be processed is phlid, Latitude, Longitude and Accuracy
Additional parameters can be added to the end of the URL as required.
Supported parameters are:
Parameter Name |
Description |
Accepted Values |
lat |
Latitude in decimal degrees |
From -90 To 90 |
lon |
Longitude in decimal degrees |
From -180 To 180 |
acc |
Fix accuracy in metres |
>=0 |
tim |
Time of fix |
Unix Time |
phlid |
The device ID as configured in HS3 for the user |
Integer >0 |
spd |
Speed in whatever units the plug-in is configured for |
>=0 |
crs |
Fix Course in degrees |
From 0 To 360 |
prv |
Fix Provider |
0=Unknown 1=GPS 2=Network 3=WiFi |
chg |
Device Charging State |
0=Not Charging 1=Charging |
dvs |
Device Online State |
0=Off-Line 1=On-Line |
alt |
Altitude in Metres or Feet |
Any numerical value |
bat |
Battery Level in % |
From 0 To 100 |
Created with the Personal Edition of HelpNDoc: Benefits of a Help Authoring Tool