Pontosense Integration API (Part MQTT) v4.0.2

Accepts one of the following messages:

• #0Last Will and Testament Report

  Device offline notification

  • application/json

  Message IDdevice.offline

  Report the last will and testament of a device. Regarded as an offline notification.

  Payload

  Expand all

  object

  method

  required

  string

  Const:"lwt.report"

  params

  Expand all

  required

  object

  sn

  required

  string

  The serial number of the device

  orgId

  required

  integer

  format: int64

  The organization ID (client ID) of the sensor

  Additional properties are allowed.

  Additional properties are allowed.

  Examples

  Payload

  {
    "method": "lwt.report",
    "params": {
      "sn": "ATR_GN_P4-250120-09527",
      "orgId": 153498752
    }
  }
  

  This example has been generated automatically.

• #1Event Report

  Device event notification

  • application/json

  Message IDdevice.events

  MQTT Event Message Format Overview
  This message reports various events from a device. Multiple event types may be included in a single message.
  The presence of a specific event property indicates that the corresponding event has occurred.

  • Fall Detected
    • A fall is detected when the fall list was previously empty and now contains one or more entries.
      Each entry includes relative coordinates (x, y, z) of the fallen person in the room.
    • Example:

      fall: [] -> fall: [{id: 1, x: 154, y: 234, z: 174}]
      

  • Fall Recovered
    • A fall recovery is detected when the fall list was previously not empty and now becomes empty.
    • Example:

      fall: [{id: 1, x: 154, y: 234, z: 174}] -> fall: []
      

  • Bed In Detected
    • A bed-in event is detected when the bedin list was previously empty and now contains one or more entries.
      Each entry includes the relative position of the person in bed.
    • Example:

      bedin: [] -> bedin: [{id: 1, x: 154, y: 234, z: 174}]
      

  • Bed Exit Detected
    • A bed exit is detected when the bedin list was previously not empty and now becomes empty.
    • Example:

      bedin: [{id: 1, x: 154, y: 234, z: 174}] -> bedin: []
      

  • Couch In Detected
    • A couch-in event is detected when the couchin list was previously empty and now contains one or more entries.
      Each entry includes the relative position of the person on the couch.
    • Example:

      couchin: [] -> couchin: [{id: 1, x: 154, y: 234, z: 174}]
      

  • Door In Detected
    • A door-in event is detected when the doorin list was previously empty and now contains one or more entries.
      Each entry includes the relative position of the person entering through the door.
    • Example:

      doorin: [] -> doorin: [{id: 1, x: 154, y: 234, z: 174}]
      

  • Door Out Detected
    • A door-out event is detected when the doorout list was previously empty and now contains one or more entries.
      Each entry includes the relative position of the person exiting through the door.
    • Example:

      doorout: [] -> doorout: [{id: 1, x: 154, y: 234, z: 174}]
      

  • Radar Error
    • A radar error is detected when the radar.error value is non-zero.
    • Example:

      radar: {error: 1}
      

    • error code:
      • 1: The radar loses contact.
      • 2: angle error.
      • 3: Insufficient radar voltage
  • Radar Upgrade Result
    • The upgrade result is determined from the upgrade object:
      • state: indicates the upgrade status
      • code: indicates the result
    • Example:

      upgrade: {"state": 2, "code": 0}
      

    • State Values:
      • 1: Upgrading
      • 2: Upgrade complete
    • Result Codes:
      • 0: Success
      • 2: Power down
      • 3: Radar crash post-upgrade
      • 4: Radar switching failed
      • 6: No config received
      • 7: OTA task creation failed
      • 8: Manually canceled upgrade
      • 9: Auto-retry limit exceeded
      • 10: Wi-Fi disconnected
      • 11: HTTP connection failed
      • 12: HTTP connection closed
      • 13: HTTP data read error
      • 14: Firmware header mismatch
      • 15: Firmware MD5 verification failed
      • 16: Firmware cache partition error
      • 17: HTTP download timeout
      • 30: Radar unresponsive or timeout
      • 31: No transmission start from radar
      • 32: Radar data transmission failed
      • 33: Radar data transmission timeout
      • 34: Radar disconnected
      • 51: ESP32 OTA partition open failed
      • 52: ESP32 OTA write failed
      • 53: ESP32 firmware verification failed
      • 54: ESP32 failed to set startup partition

  Payload

  Expand all

  object

  method

  required

  string

  Const:"event.report"

  params

  Expand all

  required

  object

  sn

  required

  string

  The serial number of the device

  orgId

  required

  integer

  format: int64

  The organization ID (client ID) of the sensor

  online

  Expand all

  object

  Reported when the device establishes connection to the MQTT broker

  Additional properties are allowed.

  presence

  Expand all

  object

  Reported when the device detects any changes in occupancy status, such as:

  • People entering or leaving the room
  • Target position changes between zones (bed, couch)
  • Fall detection or potential fall events

  bedin

  Expand all

  array<object allOf>

  >= 0

  List of targets detected lying on the bed

  Items:

  object allOf

  The detected target object

  Consists of <anonymous-schema-11>:

  Expand all

  object

  id

  required

  integer

  [ 1 .. 255 ]

  The ID of a detected target in the sensor

  Additional properties are allowed.

  And of position:

  Expand all

  object

  The position of a target in 3D space (measured in centimeters)

  x

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the left side of the sensor field of view

  y

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the front of the sensor field of view

  z

  required

  integer

  format: int32[ 0 .. 200 ]

  Vertical height from the floor

  Additional properties are allowed.

  Additional properties are allowed.

  couchin

  Expand all

  array<object allOf>

  >= 0

  List of targets detected sitting or lying on the couch

  Items:

  object allOf

  The detected target object

  Consists of <anonymous-schema-11>:

  Expand all

  object

  id

  required

  integer

  [ 1 .. 255 ]

  The ID of a detected target in the sensor

  Additional properties are allowed.

  And of position:

  Expand all

  object

  The position of a target in 3D space (measured in centimeters)

  x

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the left side of the sensor field of view

  y

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the front of the sensor field of view

  z

  required

  integer

  format: int32[ 0 .. 200 ]

  Vertical height from the floor

  Additional properties are allowed.

  Additional properties are allowed.

  doorin

  Expand all

  array<object allOf>

  >= 0

  List of targets detected entering through a door

  Items:

  object allOf

  The detected target object

  Consists of <anonymous-schema-11>:

  Expand all

  object

  id

  required

  integer

  [ 1 .. 255 ]

  The ID of a detected target in the sensor

  Additional properties are allowed.

  And of position:

  Expand all

  object

  The position of a target in 3D space (measured in centimeters)

  x

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the left side of the sensor field of view

  y

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the front of the sensor field of view

  z

  required

  integer

  format: int32[ 0 .. 200 ]

  Vertical height from the floor

  Additional properties are allowed.

  Additional properties are allowed.

  doorout

  Expand all

  array<object allOf>

  >= 0

  List of targets detected exiting through a door

  Items:

  object allOf

  The detected target object

  Consists of <anonymous-schema-11>:

  Expand all

  object

  id

  required

  integer

  [ 1 .. 255 ]

  The ID of a detected target in the sensor

  Additional properties are allowed.

  And of position:

  Expand all

  object

  The position of a target in 3D space (measured in centimeters)

  x

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the left side of the sensor field of view

  y

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the front of the sensor field of view

  z

  required

  integer

  format: int32[ 0 .. 200 ]

  Vertical height from the floor

  Additional properties are allowed.

  Additional properties are allowed.

  pfall

  Expand all

  array<object allOf>

  >= 0

  List of targets with movement patterns suggesting a potential fall (requires confirmation)

  Items:

  object allOf

  The detected target object

  Consists of <anonymous-schema-11>:

  Expand all

  object

  id

  required

  integer

  [ 1 .. 255 ]

  The ID of a detected target in the sensor

  Additional properties are allowed.

  And of position:

  Expand all

  object

  The position of a target in 3D space (measured in centimeters)

  x

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the left side of the sensor field of view

  y

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the front of the sensor field of view

  z

  required

  integer

  format: int32[ 0 .. 200 ]

  Vertical height from the floor

  Additional properties are allowed.

  Additional properties are allowed.

  fall

  Expand all

  array<object allOf>

  >= 0

  List of targets confirmed as fallen based on position and duration thresholds

  Items:

  object allOf

  The detected target object

  Consists of <anonymous-schema-11>:

  Expand all

  object

  id

  required

  integer

  [ 1 .. 255 ]

  The ID of a detected target in the sensor

  Additional properties are allowed.

  And of position:

  Expand all

  object

  The position of a target in 3D space (measured in centimeters)

  x

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the left side of the sensor field of view

  y

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the front of the sensor field of view

  z

  required

  integer

  format: int32[ 0 .. 200 ]

  Vertical height from the floor

  Additional properties are allowed.

  Additional properties are allowed.

  other

  Expand all

  array<object allOf>

  >= 0

  List of targets in normal state (not in bed, couch, or fallen)

  Items:

  object allOf

  The detected target object

  Consists of <anonymous-schema-11>:

  Expand all

  object

  id

  required

  integer

  [ 1 .. 255 ]

  The ID of a detected target in the sensor

  Additional properties are allowed.

  And of position:

  Expand all

  object

  The position of a target in 3D space (measured in centimeters)

  x

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the left side of the sensor field of view

  y

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the front of the sensor field of view

  z

  required

  integer

  format: int32[ 0 .. 200 ]

  Vertical height from the floor

  Additional properties are allowed.

  Additional properties are allowed.

  Additional properties are allowed.

  radar

  Expand all

  object

  whether the mmWave radar works properly. 0 means the radar resumes to work, otherwise, the radar is not working.

  error

  integer

  >= 0

  Additional properties are allowed.

  angle

  Expand all

  object

  The current intallation angle of the device. [pitch_min, pitch_max] and [roll_mix, roll_max] define the acceptable ranges for pitch and roll angles, respectively.

  pitch

  number

  Current pitch angle of the device in degrees.

  pitch_max

  number

  Maximum allowed pitch angle in degrees

  pitch_min

  number

  Minimum allowed pitch angle in degrees

  roll

  number

  Current roll angle of the device in degrees

  roll_max

  number

  Maximum allowed roll angle in degrees

  roll_min

  number

  Minimum allowed roll angle in degrees

  Additional properties are allowed.

  wifi

  Expand all

  object

  Wi-Fi information

  rssi

  integer

  [ -100 .. 0 ]

  Signal strength of Wi-Fi connection in dBm

  Additional properties are allowed.

  upgrade

  Expand all

  object

  Report the upgrade status of the device.

  state

  integer

  The upgrade state of the device.

  • 1: upgrading
  • 2: upgraded

  Allowed values:
  • 1
  • 2

  code

  integer

  >= 0

  The error code of the upgrade. 0 means no error, otherwise, the upgrade failed.

  Additional properties are allowed.

  Additional properties are allowed.

  Additional properties are allowed.

  Examples

  Payload

  {
    "method": "event.report",
    "params": {
      "sn": "ATR_GN_P4-250120-09527",
      "orgId": 153498752,
      "online": {},
      "presence": {
        "bedin": [
          {
            "id": 1,
            "x": 156,
            "y": 234,
            "z": 175
          }
        ],
        "couchin": [
          {
            "id": 1,
            "x": 156,
            "y": 234,
            "z": 175
          }
        ],
        "doorin": [
          {
            "id": 1,
            "x": 156,
            "y": 234,
            "z": 175
          }
        ],
        "doorout": [
          {
            "id": 1,
            "x": 156,
            "y": 234,
            "z": 175
          }
        ],
        "pfall": [
          {
            "id": 1,
            "x": 156,
            "y": 234,
            "z": 175
          }
        ],
        "fall": [
          {
            "id": 1,
            "x": 156,
            "y": 234,
            "z": 175
          }
        ],
        "other": [
          {
            "id": 1,
            "x": 156,
            "y": 234,
            "z": 175
          }
        ]
      },
      "radar": {
        "error": 0
      },
      "angle": {
        "pitch": -1,
        "pitch_max": 2,
        "pitch_min": -2,
        "roll": 0,
        "roll_max": 10,
        "roll_min": -10
      },
      "wifi": {
        "rssi": -50
      },
      "upgrade": {
        "state": 1,
        "code": 0
      }
    }
  }
  

  This example has been generated automatically.

• #2Event Notification

  Event notification

  • application/json

  Message IDevents.notifications

  Final notifications generated based on event.reports. This is preferred to event.reports if the integrators do not want to track the status of events.

  Payload

  Expand all

  object

  method

  required

  string

  Const:"event.notify"

  params

  Expand all

  required

  object

  sn

  required

  string

  The serial number of the device

  orgId

  required

  integer

  format: int64

  The organization ID (client ID) of the sensor

  type

  required

  string

  The types of notifications should be clearly defined. When a device goes offline, encounters a malfunction, or undergoes an upgrade, its previous state is interrupted and will no longer be maintained, as the new condition takes higher priority. For example, if the device was in a fall-detected state and then one of these conditions occurs, the fall state is considered interrupted. After the device recovers from the offline, malfunction, or upgrade condition, it will report its detection state again.

  • If the device is still in a fall condition, a new fall notification will be sent.
  • If the device is no longer in a fall condition, no “fall recovery” notification will be issued, since returning from a higher-priority condition to normal is still considered normal.

  device_recovered: refers specifically to recovery from either a mounting-angle skew condition or a device-malfunction condition.

  Allowed values:
  • "online"
  • "offline"
  • "occupied"
  • "vacant"
  • "bed_in"
  • "bed_out"
  • "couch_in"
  • "couch_out"
  • "door_in"
  • "door_out"
  • "fall_detected"
  • "fall_recovered"
  • "mount_angle_skewed"
  • "device_recovered"
  • "device_malfunctioning"
  • "upgrade_started"
  • "upgrade_succeeded"
  • "upgrade_failed"

  data

  Expand all

  object

  errorCode

  integer

  positions

  Expand all

  array<object>

  object

  The position of a target in 3D space (measured in centimeters)

  x

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the left side of the sensor field of view

  y

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the front of the sensor field of view

  z

  required

  integer

  format: int32[ 0 .. 200 ]

  Vertical height from the floor

  Additional properties are allowed.

  Additional properties are allowed.

  Additional properties are allowed.

  Additional properties are allowed.

  Examples

  Payload

  {
    "method": "event.notify",
    "params": {
      "sn": "ATR_GN_P4-250120-09527",
      "orgId": 153498752,
      "type": "online",
      "data": {
        "errorCode": 0,
        "positions": [
          {
            "x": 156,
            "y": 234,
            "z": 175
          }
        ]
      }
    }
  }
  

  This example has been generated automatically.

• #3Sensor Configuration Report

  Device configuration notification

  • application/json

  Message IDdevice.config

  Report the configuration of a sensor device every 30 mins.

  Payload

  Expand all

  object

  method

  required

  string

  Const:"sensor.config.report"

  params

  Expand all

  required

  object

  sn

  required

  string

  The serial number of the device

  orgId

  required

  integer

  format: int64

  The organization ID (client ID) of the sensor

  scanArea

  Expand all

  required

  object

  The scan area configuration of the sensor

  left

  required

  integer

  format: int32[ 0 .. 600 ]

  Left distance in cm

  right

  required

  integer

  format: int32[ 0 .. 600 ]

  Right distance in cm

  height

  required

  integer

  format: int32[ 200 .. 220 ]

  Mounting height of the sensor in cm

  Additional properties are allowed.

  fall

  Expand all

  object

  The fall detection configuration of the sensor.

  threshold

  integer

  [ 0 .. 90 ]

  Fall detection threshold in seconds.

  Additional properties are allowed.

  firmware

  Expand all

  object

  The firmware configuration of the sensor

  model

  integer

  format: int32

  Sensor models

  • 2: P2
  • 4: P4

  Allowed values:
  • 2
  • 4

  version

  string

  must match: ^(\d+)\.(\d+)\.(\d+)$

  The (firmware) version number in X.Y.Z format

  extra

  string

  Reserved field for clients. Allow additional data from the App.

  Additional properties are allowed.

  Additional properties are allowed.

  Additional properties are allowed.

  Examples

  Payload

  {
    "method": "sensor.config.report",
    "params": {
      "sn": "ATR_GN_P4-250120-09527",
      "orgId": 153498752,
      "scanArea": {
        "left": 300,
        "right": 300,
        "height": 220
      },
      "fall": {
        "threshold": 90
      },
      "firmware": {
        "model": 2,
        "version": "1.1.0",
        "extra": "string"
      }
    }
  }
  

  This example has been generated automatically.

• #4Location Report

  Target location notification

  • application/json

  Message IDdevice.location

  Report the location of targets from a sensor.

  Payload

  Expand all

  object

  method

  required

  string

  Const:"location.report"

  params

  Expand all

  required

  object

  sn

  required

  string

  The serial number of the device

  orgId

  required

  integer

  format: int64

  The organization ID (client ID) of the sensor

  positions

  Expand all

  required

  array<allOf>

  The id and position (in cm) of all detected targets.

  Items:

  allOf

  Consists of target:

  Expand all

  object allOf

  The detected target object

  Consists of <anonymous-schema-11>:

  Expand all

  object

  id

  required

  integer

  [ 1 .. 255 ]

  The ID of a detected target in the sensor

  Additional properties are allowed.

  And of position:

  Expand all

  object

  The position of a target in 3D space (measured in centimeters)

  x

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the left side of the sensor field of view

  y

  required

  integer

  format: int32[ 0 .. 600 ]

  Horizontal distance from the front of the sensor field of view

  z

  required

  integer

  format: int32[ 0 .. 200 ]

  Vertical height from the floor

  Additional properties are allowed.

  Additional properties are allowed.

  And of <anonymous-schema-58>:

  Expand all

  object

  state

  required

  integer

  The state of the target:

  • 40: occupied
  • 80: on couch
  • 90: in bed
  • 99: suspected fall
  • 100: fall

  Allowed values:
  • 40
  • 80
  • 90
  • 99
  • 100

  zoneId

  integer

  format: int32[ 1 .. 255 ]

  The ID of the zone in the sensor

  Additional properties are allowed.

  Additional properties are allowed.

  Additional properties are allowed.

  Examples

  Payload

  {
    "method": "location.report",
    "params": {
      "sn": "ATR_GN_P4-250120-09527",
      "orgId": 153498752,
      "positions": [
        {
          "id": 1,
          "x": 156,
          "y": 234,
          "z": 175,
          "state": 40,
          "zoneId": 1
        }
      ]
    }
  }
  

  This example has been generated automatically.

Accepts the following message:

{
  "method": "firmware.notify",
  "params": {
    "version": "1.1.0",
    "model": 2
  }
}