Resource: Beacon
Details of a beacon device.
JSON representation | |
---|---|
{ "beaconName": string, "advertisedId": { object( |
Fields | |
---|---|
beaconName |
Resource name of this beacon. A beacon name has the format "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by the beacon and N is a code for the beacon's type. Possible values are This field must be left empty when registering. After reading a beacon, clients can use the name for future operations. |
advertisedId |
The identifier of a beacon as advertised by it. This field must be populated when registering. It may be empty when updating a beacon record because it is ignored in updates. When registering a beacon that broadcasts Eddystone-EID, this field should contain a "stable" Eddystone-UID that identifies the beacon and links it to its attachments. The stable Eddystone-UID is only used for administering the beacon. |
status |
Current status of the beacon. Required. |
placeId |
The Google Places API Place ID of the place where the beacon is deployed. This is given when the beacon is registered or updated, not automatically detected in any way. Optional. |
latLng |
The location of the beacon, expressed as a latitude and longitude pair. This location is given when the beacon is registered or updated. It does not necessarily indicate the actual current location of the beacon. Optional. |
indoorLevel |
The indoor level information for this beacon, if known. As returned by the Google Maps API. Optional. |
expectedStability |
Expected location stability. This is set when the beacon is registered or updated, not automatically detected in any way. Optional. |
description |
Free text used to identify and describe the beacon. Maximum length 140 characters. Optional. |
properties |
Properties of the beacon device, for example battery type or firmware version. Optional. An object containing a list of |
ephemeralIdRegistration |
Write-only registration parameters for beacons using Eddystone-EID (remotely resolved ephemeral ID) format. This information will not be populated in API responses. When submitting this data, the |
provisioningKey |
Some beacons may require a user to provide an authorization key before changing any of its configuration (e.g. broadcast frames, transmit power). This field provides a place to store and control access to that key. This field is populated in responses to A base64-encoded string. |
Status
Current status of the beacon.
Enums | |
---|---|
STATUS_UNSPECIFIED |
Do not use this value. |
ACTIVE |
The "normal" in-use state of a beacon. |
DECOMMISSIONED |
Beacon should no longer be used for any purpose. This is irreversible. |
INACTIVE |
The beacon should not be visible to mobile devices. This is reversible. |
LatLng
An object representing a latitude/longitude pair. This is expressed as a pair of doubles representing degrees latitude and degrees longitude. Unless specified otherwise, this must conform to the WGS84 standard. Values must be within normalized ranges.
Example of normalization code in Python:
def NormalizeLongitude(longitude):
"""Wraps decimal degrees longitude to [-180.0, 180.0]."""
q, r = divmod(longitude, 360.0)
if r > 180.0 or (r == 180.0 and q <= -1.0):
return r - 360.0
return r
def NormalizeLatLng(latitude, longitude):
"""Wraps decimal degrees latitude and longitude to
[-90.0, 90.0] and [-180.0, 180.0], respectively."""
r = latitude % 360.0
if r <= 90.0:
return r, NormalizeLongitude(longitude)
elif r >= 270.0:
return r - 360, NormalizeLongitude(longitude)
else:
return 180 - r, NormalizeLongitude(longitude + 180.0)
assert 180.0 == NormalizeLongitude(180.0)
assert -180.0 == NormalizeLongitude(-180.0)
assert -179.0 == NormalizeLongitude(181.0)
assert (0.0, 0.0) == NormalizeLatLng(360.0, 0.0)
assert (0.0, 0.0) == NormalizeLatLng(-360.0, 0.0)
assert (85.0, 180.0) == NormalizeLatLng(95.0, 0.0)
assert (-85.0, -170.0) == NormalizeLatLng(-95.0, 10.0)
assert (90.0, 10.0) == NormalizeLatLng(90.0, 10.0)
assert (-90.0, -10.0) == NormalizeLatLng(-90.0, -10.0)
assert (0.0, -170.0) == NormalizeLatLng(-180.0, 10.0)
assert (0.0, -170.0) == NormalizeLatLng(180.0, 10.0)
assert (-90.0, 10.0) == NormalizeLatLng(270.0, 10.0)
assert (90.0, 10.0) == NormalizeLatLng(-270.0, 10.0)
JSON representation | |
---|---|
{ "latitude": number, "longitude": number, } |
Fields | |
---|---|
latitude |
The latitude in degrees. It must be in the range [-90.0, +90.0]. |
longitude |
The longitude in degrees. It must be in the range [-180.0, +180.0]. |
IndoorLevel
Indoor level, a human-readable string as returned by Google Maps APIs, useful to indicate which floor of a building a beacon is located on.
JSON representation | |
---|---|
{ "name": string, } |
Fields | |
---|---|
name |
The name of this level. |
Stability
Expresses the expectation of a beacon's location stability.
Enums | |
---|---|
STABILITY_UNSPECIFIED |
Do not use this value. |
STABLE |
Not expected to move, for example a store's front door. |
PORTABLE |
Usually stable but may move rarely, usually within a single place, for example a store display. |
MOBILE |
Moves frequently, for example a personal item or food truck. |
ROVING |
Moves continuously in service, for example a bus or train. |
EphemeralIdRegistration
Write-only registration parameters for beacons using Eddystone-EID format. Two ways of securely registering an Eddystone-EID beacon with the service are supported:
- Perform an ECDH key exchange via this API, including a previous call to
GET /v1beta1/eidparams
. In this case the fieldsbeaconEcdhPublicKey
andserviceEcdhPublicKey
should be populated andbeaconIdentityKey
should not be populated. This method ensures that only the two parties in the ECDH key exchange can compute the identity key, which becomes a secret between them. - Derive or obtain the beacon's identity key via other secure means (perhaps an ECDH key exchange between the beacon and a mobile device or any other secure method), and then submit the resulting identity key to the service. In this case
beaconIdentityKey
field should be populated, and neither ofbeaconEcdhPublicKey
norserviceEcdhPublicKey
fields should be. The security of this method depends on how securely the parties involved (in particular the bluetooth client) handle the identity key, and obviously on how securely the identity key was generated.
See the Eddystone specification at GitHub.
JSON representation | |
---|---|
{ "beaconEcdhPublicKey": string, "serviceEcdhPublicKey": string, "beaconIdentityKey": string, "rotationPeriodExponent": number, "initialClockValue": string, "initialEid": string, } |
Fields | |
---|---|
beaconEcdhPublicKey |
The beacon's public key used for the Elliptic curve Diffie-Hellman key exchange. When this field is populated, A base64-encoded string. |
serviceEcdhPublicKey |
The service's public key used for the Elliptic curve Diffie-Hellman key exchange. When this field is populated, A base64-encoded string. |
beaconIdentityKey |
The private key of the beacon. If this field is populated, A base64-encoded string. |
rotationPeriodExponent |
Indicates the nominal period between each rotation of the beacon's ephemeral ID. "Nominal" because the beacon should randomize the actual interval. See the spec at github for details. This value corresponds to a power-of-two scaler on the beacon's clock: when the scaler value is K, the beacon will begin broadcasting a new ephemeral ID on average every 2^K seconds. |
initialClockValue |
The initial clock value of the beacon. The beacon's clock must have begun counting at this value immediately prior to transmitting this value to the resolving service. Significant delay in transmitting this value to the service risks registration or resolution failures. If a value is not provided, the default is zero. |
initialEid |
An initial ephemeral ID calculated using the clock value submitted as A base64-encoded string. |
Methods |
|
---|---|
|
Activates a beacon. |
|
Deactivates a beacon. |
|
Decommissions the specified beacon in the service. |
|
Deletes the specified beacon including all diagnostics data for the beacon as well as any attachments on the beacon (including those belonging to other projects). |
|
Returns detailed information about the specified beacon. |
|
Searches the beacon registry for beacons that match the given search criteria. |
|
Registers a previously unregistered beacon given its advertisedId . |
|
Updates the information about the specified beacon. |