LogoLogo
  • PlaceOS Documentation
  • Overview
    • Key Concepts
      • Drivers
      • Interfaces
      • Modules
      • Settings
      • Systems
      • Triggers
      • Zones
    • Languages
      • Crystal
      • TypeScript
    • Protocols
      • MQTT
      • SAML
      • OAuth2
  • How To
    • Configure PlaceOS for Microsoft 365
      • Step 1: Room Calendar Access
        • Create Azure App Registration (Application Permissions)
        • Exchange Calendar Group
        • Limit Application Permissions
        • Configure PlaceOS Calendar Driver
      • Step 2: User Authentication & Calendar Access
        • Create a PlaceOS Authentication Source
        • Create Azure App Registration (Delegated Permissions)
        • Configure PlaceOS Authentication Source
        • Add User Login Redirects
      • Concierge Access
      • Troubleshooting
        • Blocked or Blacklisted IP Error
    • Configure PlaceOS for Google Workspace
      • Google Configuration
        • Create Google Cloud Project & Enable API
        • Configure Google Cloud Service Account
        • Add Google Workplace Permissions
        • Create Google Marketplace App (optional)
        • Google Workspace Service User (RBAC)
        • Configure Access to Google Resource Calendars
      • User Authentication
        • Create a PlaceOS Authentication Source for Google
        • Create Google Cloud OAuth2 Client App
        • Configure PlaceOS Auth Source for Google
        • Add User Login Redirects
    • Deployment
      • Deploy AWS Fargate on Modular CloudFormation Stacks
      • Deploy AWS Fargate on Nested CloudFormation Stacks
      • Writing Import Scripts
    • Analytics
      • MQTT Integration
    • Backoffice
      • Add a Domain to PlaceOS
      • Backoffice File Upload
      • Configure Staff API
      • Calendar Driver
      • Enable Sensor UI
      • Bookings Driver
      • Configure a webhook
    • Authentication
      • Azure B2C
        • Azure B2C Custom Policy Framework
        • Configure PlaceOS for Azure B2C
        • 365 Room Resources on Azure B2C
      • Configure SAML SSO
        • Configure SAML2 with AD FS
        • Configure SAML2 with Auth0
        • Configure SAML2 with Azure AD
        • Configure SAML2 with Google Workspace
      • Configure OAuth2 SSO
      • X-API Keys
      • Bearer tokens
    • Location Services
      • Location Services
      • Area Management
      • Discovering User Devices
      • Locating Users on a Network
      • People Finding with Cisco Meraki on PlaceOS
      • People Finding with Juniper Mist on PlaceOS
    • Notifications
      • Catering Orders
    • User Interfaces
      • Booking Panel App
      • Workplace App
      • Native Booking Panel App
      • Deploy a Frontend Interface
      • Microsoft Outlook Plugin
      • Configure Endpoint Auto Login
      • SVG Map Creation
      • Configuring a default UI
  • Tutorials
    • Setup a dev environment
    • Backend
      • Troubleshooting Backend Failures
      • Import Bookable Rooms
      • Writing A Driver
        • Testing drivers
        • ChatGPT / LLM Capabilities
          • Native GPT Plugins
      • Testing Internal Builds
    • Backoffice
      • Adding Drivers & Modules
      • Add Zone Structure
    • Common Configurations
      • Asset Manager
      • Catering
      • Locker Booking
      • Webex Instant Connect
      • Desk booking
      • Sensor Data Collection
        • Configure Kontakt IO
        • Configuring Meraki
        • Configuring DNA Spaces
      • Elevated Privileges
  • Reference
    • API
      • Real-time Websocket
      • Rest API
      • Staff API
    • Drivers
      • PlaceOS
        • Bookings
        • Staff API
        • Visitor Mailer
        • Lockers
      • Microsoft
        • Graph API
    • PlaceOS Skills
    • Privacy Policy
    • Recommended Products
    • Supported Integrations
    • System Architecture
    • System Functionality & Requirements
    • Infrastructure Requirements
    • Security Compliance
      • FAQ
      • GDPR
      • Security
    • Microsoft Azure Permissions
  • Glossary
  • 🎯PlaceOS Roadmap
  • 🆘PlaceOS Support
  • 👩‍💻PlaceOS Github
  • 📝PlaceOS Changelog
Powered by GitBook
On this page
  • Configuration
  • Data Model
  • Overview
  • Desk IDs
  • Location Data
  • Areas
  • Desk ID Metadata
  • Area Metadata
  • Defining Area Metadata
Export as PDF
  1. How To
  2. Location Services

Area Management

IoT data model for display and analytics

PreviousLocation ServicesNextDiscovering User Devices

Last updated 3 years ago

This driver provides the bindings for overlaying location data on a map. It exposes the following data:

  1. Overview of building use and recommended levels based on capacity

  2. A list of Areas on each level and the counts of people in those areas

  3. Location data for the levels, wireless and desks

  4. List of known desks on the level, for simplified processing of real-time visualizations

Each building needs one of these modules, and they rely on for collecting data.

Configuration

By default the view updates once a minute, you can increase this batching rate based on requirements. Intervals lower than about 15 seconds are not worth using, as it's still limited by systems which update once per minute. Locations Services can also inform Area Management of updates. This increases the batching rate to at most every 3 seconds.

# The building this driver is monitoring
building: zone-12345

# Poll rate in seconds
poll_rate: 15

# 1.0 == no duplicate devices
# 0.8 == 20% of devices are probably duplicates (phone + laptop)
# NOTE:: that phones turn off their wifi regularly so are often not represented in the data
duplication_factor: 0.8

# Driver to query for location information
location_service: LocationServices

You'll also need to configure the PlaceOS Staff API driver for getting zone data via the public API

    # Create a service account for API access
    username:     "service_account@placeos.com"
    password:     "put this in an encrypted tab"

    # Create or grab an application for accessing the API
    client_id:    ""
    redirect_uri: ""

Data Model

This is the state data that is exposed. It's used for display on a real-time interface and for analytics. Frontends can binding to the data points described below.

Overview

This provides an overview of the building.

# overview is the binding name
"overview": {
  # The levels are represented by the zone ids
  "zone-Epaq-dE1DaH": {
    # Desk count based on `desks` metadata in the zone
    # if falls back to the zone.count field otherwise
    "desk_count": 268,
    "desk_usage": 0,
    # This is the capacity of the space, set in zone.capacity field
    "device_capacity": 100,
    # This is the raw device count
    "device_count": 70,
    # This is the adjusted count based on the duplication factor
    "estimated_people": 56,
    "percentage_use": 56,
    # The higher the recommendation number the better for recommending
    "recommendation": 102
  },

  "zone-Epa~Jlq--l0": {
    "desk_count": 0,
    "desk_usage": 0,
    "device_capacity": 0,
    "device_count": 75,
    "estimated_people": 60,
    "percentage_use": 100,
    "recommendation": -6060
  }
}

Desk IDs

This provides the list of desk IDs in a system as a binding, allowing the frontend to highlight available desks.

  • Available desks = all desks - (in-use or booked)

# Bind to `level_id:desk_ids`
"zone-EmWVhHG3Bhz:desk_ids": [
  "table-01.002",
  "table-01.003",
  "table-01.004",
  "table-01.005",
  "table-01.006",
  "table-01.007",
  "table-01.008"
]

Location Data

This binding has all the location data for a level (desks and wireless). It allows for desk highlighting and a point cloud.

The data returned doesn't include usernames. It returns MAC addresses (if available) which can resolve to a user via the LocationServices module.

# The level id is the binding
"zone-EmWVhHG3Bhz": {
  # The locations of devices on the level (wireless and desks)
  "value": [
    {
      "location": "wireless",
      "coordinates_from": "bottom-left",
      "x": 22.389704894550505,
      "y": 7.934026150363014,
      "lon": 55.27476066828535,
      "lat": 25.20106100633537,
      "s2_cell_id": "3e5f4281459c",
      "mac": "3868a4a31a50",
      "variance": 9.62534032222287,
      "last_seen": 1603168962,
      "map_width": 79.3282194366595,
      "map_height": 48.568208517912
    },
    {
      "location": "desk",
      "capacity": 1,
      "at_location": 1,
      "map_id": "desk-4-1006",
      "mac": "66e0fd1279ce",
      "level": "zone_1234",
      "building": "zone_1234"
    }
  ],

  # These are Time Series hints on how to store these data points
  "ts_hint": "complex",

  # convert x to xloc when storing in InfluxDB
  "ts_map": {
    "x": "xloc",
    "y": "yloc"
  },

  # tag this data so it's indexed (improving searching)
  "ts_tag_keys": [
    "s2_cell_id"
  ],
  "ts_tags": {
    "pos_building": "zone-FzNP2idoAOj",
    "pos_level": "zone-FzNYawvBxWD"
  }
}

Use LocationServices.check_ownership_of(mac_address) to determine who is at any of the locations

Areas

It's possible to have the system count the number of devices in an area on the map. These areas, like desk ids, are defined in metadata using a Backoffice plugin.

# the binding is `level_id:areas`
"zone-FBkhCVwD3Af:areas": {
  # Array of area counts, the polygon coordinates are in the metadata
  "value": [
    {
       "area_id": "area-1234",
       "name": "Level 1 Desks",
       "count": 15
    },
    {
      "area_id": "zone-09.C",
      "name": "Level 1 Lounge",
      "count": 4
    }
  ],

  # Time Series storage hints
  "ts_hint": "complex",

  # add this field to the records above
  "ts_fields": {
    "pos_level": "zone-FzNYawvBxWD"
  },

  # add this tag
  "ts_tags": {
    "pos_building": "zone-FzNP2idoAOj"
  }
}

Desk ID Metadata

The desk ID metadata is stored in level zone metadata

  • With the key desks

  • The id of the desks are extracted from this data

[
  {
    "bookable": false,
    "group": null,
    "id": "table-01.002",
    "name": "Desk 002"
  },
  {
    "bookable": true,
    "group": null,
    "id": "table-01.003",
    "name": "Desk 003"
  }
]

Area Metadata

Area metadata is stored in level zone metadata

  • With the key map_regions

  • The area_id is extracted from this data

{
  # Map information
  "url": "https://s3-ap-southeast-2.amazonaws.com/os.place.tech/mck-placeos-poc.aca.im/16049826805781672737.svg",
  "width": 100,
  "height": 55.975,

  # Area definitions
  "areas": [
    {
      "id": "zone-10.C",
      "type": "Feature",
      "feature_type": "section",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
              0.738,
              0.5
          ],
          [
              0.337,
              0.5
          ],
          [
              0.337,
              0.881
          ],
          [
              0.738,
              0.881
          ]
        ]
      }
    }
  ]
}

Defining Area Metadata

Areas are defined using a Backoffice plugin. To enable the plugin:

  1. From the domains tab, select the domain you wish to enable

  2. Select the config settings tab for that domain

  3. Enter the following configuration

{
  "backoffice": {
    "extend": {
      "zones": {
        "Map": {
          "conditions": [
            [
              "map_id",
              "truthy",
              ""
            ]
          ],
          "url": "https://map-region.editor.place.tech?src={{map_id}}"
        }
      }
    }
  }
}

Once configured, there is an extra tab added to zones where you can graphically define areas on the map

Location Services