Skip to content

Yanzi API Reference

Cirrus Messages

AddUnitPropertyRequest

Request message used to add a property to a unit. It contains the UnitAddress of the unit and the UnitProperty to be added. Only for list properties.

{
  "messageType":"AddUnitPropertyRequest",
  "timeSent":1631549626045,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626045,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  },
  "unitProperty":{
    "resourceType":"UnitProperty",
    "timeCreated":1631549626045,
    "name":"dataSource",
    "value":"EUI64-0080E10300011111-3-Humd"
  },
  "argumentList":[]
}

AddUnitPropertyResponse

Response for AddUnitPropertyRequest. Contains the respective ResponseCode, unit address and the unit property objects.

{
  "messageType":"AddUnitPropertyResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626076,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626076,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  },
  "unitProperty":{
    "resourceType":"UnitProperty",
    "timeCreated":1631549626076,
    "name":"dataSource",
    "value":"EUI64-0080E10300011111-3-Humd"
  }
}

AuthenticateDeviceRequest

Request message to authenticate and accept a new device in a system. Can contain a position and a List of Unit Properties that will be set when the device is provisioned in the system.

{
  "messageType":"AuthenticateDeviceRequest",
  "timeSent":1631549626077,
  "list":[
    {
      "resourceType":"UnitProperty",
      "name":"BIM",
      "value":"1234"
    }
  ],
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626077,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456",
    "serverDid":"EUI64-0080E10300012345"
  },
  "position":{
    "resourceType":"SamplePosition",
    "timeCreated":1631549626077,
    "sampleTime":1631549626077,
    "longitude":12345.678,
    "latitude":23456.789,
    "altitude":34567.891,
    "timeOfPosition":1448539086,
    "positionType":{
      "resourceType":"PositionType",
      "name":"fullPosition"
    },
    "accuracy":12.34,
    "provider":"Test Provider",
    "isStatic":true,
    "floorLevel":4
  }
}

AuthenticateDeviceResponse

Response message for AuthenticateDeviceRequest.

{
  "messageType":"AuthenticateDeviceResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626079,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626079,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456",
    "serverDid":"EUI64-0080E10300012345"
  }
}

ClientPushData

Used to asynchronously send data from the client without a prior individual request. Currently only supports a SampleList with a SamplePosition to modify the position of a Device

{
  "messageType":"ClientPushData",
  "timeSent":1631549626079,
  "list":[
    {
      "resourceType":"SampleList",
      "dataSourceAddress":{
        "resourceType":"DataSourceAddress",
        "did":"EUI64-0080E10300099999",
        "locationId":"123456",
        "variableName":{
          "resourceType":"VariableName",
          "name":"positionLog"
        },
        "instanceNumber":0
      },
      "list":[
        {
          "resourceType":"SamplePosition",
          "timeCreated":1631549626079,
          "sampleTime":1631549626079,
          "longitude":12345.678,
          "latitude":23456.789,
          "timeOfPosition":1448539086,
          "positionType":{
            "resourceType":"PositionType",
            "name":"latLongTimeFloor"
          },
          "floorLevel":4
        }
      ]
    }
  ]
}

ControlRequest

Request message to change values or the status of a unit (e.g. turn on/off a lamp). It contains a ControlValue object and a UnitAddress object. Only Yanzi Plug and Yanzi Lamp can be controlled using ControlValueBinary.

{
  "messageType":"ControlRequest",
  "timeSent":1631549626081,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626081,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  },
  "did":"EUI64-0080E10300099999",
  "controlValue":{
    "resourceType":"ControlValueBinary",
    "value":true
  },
  "value":{
    "resourceType":"ControlValueBinary",
    "controlValue":true
  }
}

ControlResponse

Response message for ControlRequest.

{
  "messageType":"ControlResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626082
}

CreateUnitRequest

Requests the creation of a unit indicating its UnitType and a LocationAddress. Can contain a list of UnitProperties or CustomProperties to be assigned after creation.

{
  "messageType":"CreateUnitRequest",
  "timeSent":1631549626083,
  "list":[
    {
      "resourceType":"UnitProperty",
      "timeCreated":1631549626083,
      "name":"logicalName",
      "value":"Conference Room Orange"
    }
  ],
  "unitType":{
    "resourceType":"UnitType",
    "name":"chair"
  },
  "locationAddress":{
    "resourceType":"LocationAddress",
    "timeCreated":1631549626083,
    "locationId":"123456"
  },
  "customPropertyList":[
    {
      "resourceType":"CustomPropertyDTO",
      "timeCreated":1631549626083,
      "name":"_my_custom_property",
      "value":"RWNvbm9teQ=="
    }
  ]
}

CreateUnitResponse

Response message for CreateUnitRequest.

{
  "messageType":"CreateUnitResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626084,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626084,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456",
    "serverDid":"EUI64-0080E10300012345"
  }
}

DeleteUnitRequest

Requests the deletion of a unit indicated by the did in the UnitAddress. Currently, this operation can only be applied on Assets.

WARNING: THIS WILL PREVENT ACCESS TO THE DEVICE/ASSET DATABASE

{
  "messageType":"DeleteUnitRequest",
  "timeSent":1631549626084,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626084,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  }
}

DeleteUnitResponse

Response message for DeleteUnitsRequest.

{
  "messageType":"DeleteUnitResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626085,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626085,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  }
}

ErrorResponse

This response is returned if there is an error processing or sending a Cirrus request

{
  "messageType":"ErrorResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"errorDestinationUnavailable"
  },
  "responseMessage":"Coulnd't find sensor on the specified gateway",
  "timeSent":1631549626085
}

GetAcceptListRequest

Used to ask for units that have been discovered by a location and either can be or have been accepted. It requires a LocationAddress object.

{
  "messageType":"GetAcceptListRequest",
  "timeSent":1631549626085,
  "locationAddress":{
    "resourceType":"LocationAddress",
    "locationId":"123456"
  }
}

GetAcceptListResponse

Response for GetAcceptListRequest message. It contains a list of AcceptEntityDTOs.

{
  "messageType":"GetAcceptListResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626086,
  "list":[
    {
      "resourceType":"AcceptEntityDTO",
      "timeCreated":1631549626086,
      "timeWhenAccepted":1428996894,
      "timeFirstSeen":1631549616086,
      "acceptState":{
        "resourceType":"DeviceAcceptState",
        "name":"discovered"
      },
      "acceptUserid":"giorgos@yanzi.se",
      "did":"EUI64-0080E10300099999",
      "productType":"0090DA12121212",
      "inetAddress":"178.45.224.13",
      "macAddress":"00-14-22-01-23-45",
      "gwdid":"EUI64-0080E10300012345",
      "locationId":"123456"
    }
  ],
  "locationAddress":{
    "resourceType":"LocationAddress",
    "timeCreated":1631549626086,
    "locationId":"123456",
    "serverDid":"EUI64-0090DAFFFF0040A9"
  }
}

GetAccountsRequest

Request message to ask for all the accounts that the user has access to.

{
  "messageType":"GetAccountsRequest"
}

GetAccountsResponse

Response for GetAccountsRequest. Contains a list of AccountDTOs to which the user belongs.

{
  "messageType":"GetAccountsResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626087,
  "list":[
    {
      "resourceType":"AccountDTO",
      "timeCreated":1631549626087,
      "accountNumber":"156468",
      "accountName":"TestAccount",
      "timeModified":1427705889,
      "owner":"test@yanzi.se",
      "roles":[
        {
          "resourceType":"AccountUserRole",
          "userId":"test@yanzi.se",
          "systemUserAcl":{
            "resourceType":"SystemUserAcl",
            "name":"admin"
          }
        },
        {
          "resourceType":"AccountUserRole",
          "userId":"support@yanzi.se",
          "systemUserAcl":{
            "resourceType":"SystemUserAcl",
            "name":"reader"
          }
        }
      ],
      "admDomainId":"yanzi",
      "admDomainParentAccount":"15487"
    }
  ]
}

GetCustomPropertyRequest

Request message used to get a specific CustomProperty object from a Location, Unit or DataSource. It contains the address and the name of the property that needs to be retrieved.

{
  "messageType":"GetCustomPropertyRequest",
  "timeSent":1631549626089,
  "address":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626089,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  },
  "name":"_my_custom_property"
}

GetCustomPropertyResponse

Response for GetCustomPropertyRequest. Contains the requested address and a list of CustomProperty objects containing the requested property for the address.

{
  "messageType":"GetCustomPropertyResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626089,
  "list":[
    {
      "resourceType":"CustomPropertyDTO",
      "timeCreated":1631549626089,
      "name":"_kira_department",
      "value":"RWNvbm9teQ=="
    }
  ],
  "address":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626089,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  }
}

GetDataSourceAddressesRequest

Request message to ask for all the different dataSources that a unit can report. It needs a UnitAddress to identify the unit.

{
  "messageType":"GetDataSourceAddressesRequest",
  "timeSent":1631549626090,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626090,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  }
}

GetDataSourceAddressesResponse

Response for GetDataSourceAddressesRequest message. It contains all the different data that a unit can report as a list of DataSourceAddress objects.

{
  "messageType":"GetDataSourceAddressesResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626090,
  "list":[
    {
      "resourceType":"DataSourceAddress",
      "timeCreated":1631549626090,
      "did":"EUI64-0080E10300099999",
      "locationId":"123456",
      "serverDid":"EUI64-0080E10300012345",
      "variableName":{
        "resourceType":"VariableName",
        "name":"relativeHumidity"
      },
      "instanceNumber":5,
      "instanceName":"Humidity Source",
      "valueTypes":[
        {
          "resourceType":"ValueTypeDTO",
          "key":"humidity",
          "dataType":"number",
          "quantityKind":"humidity",
          "valueUnit":"%"
        },
        {
          "resourceType":"ValueTypeDTO",
          "key":"temperature",
          "dataType":"number",
          "quantityKind":"temperature",
          "valueUnit":"K"
        }
      ]
    }
  ],
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626090,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456",
    "serverDid":"EUI64-0080E10300012345"
  }
}

GetLocationsRequest

Request message to ask for all locations that the user has access to.

{
  "messageType":"GetLocationsRequest",
  "timeSent":1631549626092
}

GetLocationsResponse

Response forGetLocationsRequest. It contains a list of all LocationDTOs that the user has access to. access to.

{
  "messageType":"GetLocationsResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626092,
  "list":[
    {
      "resourceType":"LocationDTO",
      "timeCreated":1631549626092,
      "locationAddress":{
        "resourceType":"LocationAddress",
        "timeCreated":1631549626092,
        "locationId":"123456",
        "serverDid":"EUI64-0090DAFFFF0040A9"
      },
      "timeModified":1631549626392,
      "accountId":"262468578",
      "name":"Beach House",
      "gwdid":"EUI64-12411261342",
      "multiLocationParent":"991579",
      "isMultiLocation":false,
      "propertyList":[
        {
          "resourceType":"PropertyDTO",
          "name":"activityLevel",
          "value":"medium"
        }
      ]
    }
  ]
}

GetPropertyRequest

Generic Request message used to get a specific LocationProperty object object from a Location, Unit or DataSource. It contains the target address and the name of the property that needs to be retrieved. Currently supports timeZone and locationType using a LocationAddress.

{
  "messageType":"GetPropertyRequest",
  "timeSent":1631549626093,
  "address":{
    "resourceType":"LocationAddress",
    "timeCreated":1631549626093,
    "locationId":"123456"
  },
  "name":"timeZone"
}

GetPropertyResponse

Response for GetLocationPropertyRequest. Contains the requested target's address and a list of LocationProperty objects containing the requested property for the target.

{
  "messageType":"GetPropertyResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626093,
  "list":[
    {
      "resourceType":"PropertyDTO",
      "timeCreated":1631549626093,
      "name":"timeZone",
      "value":"PST"
    }
  ],
  "address":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626093,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456",
    "serverDid":"EUI64-0080E10300012345"
  }
}

GetSamplesRequest

Request message used to retrieve historical data samples. Requires a DataSourceAddress that uniquely identifies the origin of the Samples and a TimeSerieSelection that will define the Range of Samples received

{
  "messageType":"GetSamplesRequest",
  "dataSourceAddress":{
    "resourceType":"DataSourceAddress",
    "timeCreated":1631549626093,
    "did":"EUI64-0080E10300099999-3-Humd",
    "locationId":"123456",
    "variableName":{
      "resourceType":"VariableName",
      "name":"relativeHumidity"
    },
    "instanceNumber":0
  },
  "timeSerieSelection":{
    "resourceType":"TimeSerieSelection",
    "timeStart":1122334455876,
    "numberOfSamplesBeforeStart":10
  }
}

GetSamplesResponse

Response for GetSamplesRequest. It contains a SampleList with samples that fit the criteria set by the corresponding request.

{
  "messageType":"GetSamplesResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626094,
  "sampleListDto":{
    "resourceType":"SampleList",
    "dataSourceAddress":{
      "resourceType":"DataSourceAddress",
      "timeCreated":1631549626094,
      "did":"EUI64-0080E10300099999-3-Humd",
      "locationId":"123456",
      "variableName":{
        "resourceType":"VariableName",
        "name":"relativeHumidity"
      },
      "instanceNumber":0
    },
    "timeCreated":1631549626094,
    "range":{
      "resourceType":"Range",
      "timeCreated":1631549626094,
      "timeStart":1631549326094,
      "timeEnd":1631549626094,
      "numberOfSamples":50
    },
    "list":[
      {
        "resourceType":"SampleHumidity",
        "timeCreated":1631549626094,
        "sampleTime":1631549626094,
        "value":30.5,
        "temperature":296.45
      }
    ]
  }
}

GetUnitPropertyRequest

Request message used to get a specific UnitProperty object from a unit. It contains the UnitAddress and the name of the property that needs to be retrieved.

{
  "messageType":"GetUnitPropertyRequest",
  "timeSent":1631549626094,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626094,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  },
  "name":"logicalName"
}

GetUnitPropertyResponse

Response for GetUnitPropertyRequest. Contains the requested unit's UnitAddress and a list of UnitProperty objects containing the requested property for the unit.

{
  "messageType":"GetUnitPropertyResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626095,
  "list":[
    {
      "resourceType":"UnitProperty",
      "timeCreated":1631549626095,
      "name":"logicalName",
      "value":"Conference Room Orange"
    }
  ],
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626095,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  }
}

GetUnitsRequest

Request message used to ask for units that belong to a specific location. It contains a LocationAddress object. Alternatively, locationAddress can be set as a UnitAddress in order to request a specific unit.

The first message is a simple example for GetUnitsRequest containing only the mandatory fields.

The second message is the request with many other advanced attributes, and request as received by the Cirrus API Server.

The Request can optionally also contian a list of MatchDTO. If any present, only units matching the DTOs will be returned in the response.

{
  "messageType":"GetUnitsRequest",
  "timeSent":1631549626095,
  "locationAddress":{
    "resourceType":"LocationAddress",
    "locationId":"123456"
  },
  "matchList":[
    {
      "resourceType":"MatchDTO",
      "name":"did",
      "matchType":"equals",
      "value":"EUI64-0080E10300054251"
    },
    {
      "resourceType":"MatchDTO",
      "name":"lifeCycleState",
      "matchType":"any",
      "value":"present"
    }
  ]
}

GetUnitsResponse

Response for GetUnitsRequest. It contains a list of units that belong to a specific location.

{
  "messageType":"GetUnitsResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626096,
  "list":[
    {
      "resourceType":"UnitDTO",
      "timeCreated":1631549626096,
      "unitAddress":{
        "resourceType":"UnitAddress",
        "timeCreated":1631549626096,
        "did":"EUI64-0080E10300099999",
        "locationId":"123456",
        "serverDid":"EUI64-0080E10300012345"
      },
      "productType":"09876543210987",
      "lifeCycleState":{
        "resourceType":"LifeCycleState",
        "name":"shadow"
      },
      "isChassis":true,
      "chassisDid":"0999999999999",
      "unitTypeFixed":{
        "resourceType":"UnitType",
        "name":"inputMotion"
      },
      "isNameSetByUser":true,
      "nameSetByUser":"Door's Motion",
      "defaultNameSetBySystem":"Motion-12AB",
      "userId":"giorgos@yanzi.se",
      "unitAcl":{
        "resourceType":"UnitAcl",
        "name":"operator"
      },
      "subunitIdentifier":0
    }
  ],
  "locationAddress":{
    "resourceType":"LocationAddress",
    "timeCreated":1631549626096,
    "locationId":"123456",
    "serverDid":"EUI64-0090DAFFFF0040A9"
  }
}

GetUserRequest

Request message to ask for information about the user.

{
  "messageType":"GetUserRequest",
  "timeSent":1631549626097
}

GetUserResponse

Response for GetUserRequest. It contains a UserDTO object.

{
  "messageType":"GetUserResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626097,
  "userDetails":{
    "resourceType":"UserDTO",
    "timeCreated":1631549626097,
    "yanziId":"616946",
    "language":"Swedish",
    "firstName":"Alan",
    "lastName":"Smith",
    "streetAddress":"Vagen 123",
    "postalCode":"55133",
    "city":"Stockholm",
    "country":"Sweden",
    "cirrusAccess":true,
    "cliAccess":false,
    "isDeveloperAllowed":false,
    "isSupportAllowed":false,
    "isCopAdmin":false,
    "admDomainList":[
      "yanzi",
      "sonera"
    ],
    "timeAcceptedTerms":1525771028000
  }
}

ListUnitPropertiesRequest

Request message used to get all UnitProperty objects from a unit. It contains the UnitAddress of the unit to get its properties from.

{
  "messageType":"ListUnitPropertiesRequest",
  "timeSent":1631549626098,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626098,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  }
}

ListUnitPropertiesResponse

Response for ListUnitPropertiesRequest. Contains the respective UnitAddress and the complete list of UnitProperty objects for the given unit.

{
  "messageType":"ListUnitPropertiesResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626098,
  "list":[
    {
      "resourceType":"UnitProperty",
      "timeCreated":1631549626098,
      "name":"logicalName",
      "value":"Conference Room Orange"
    },
    {
      "resourceType":"UnitProperty",
      "timeCreated":1631549626098,
      "name":"dataSource",
      "value":"EUI64-0123456789012345"
    }
  ],
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626098,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  }
}

LoginRequest

Request Message to establish an authenticated connection through Cirrus API. It requires a user's credentials (i.e. username and password). If there is an available sessionId it can be provided as an alternative to the user's credentials.

{
  "messageType":"LoginRequest",
  "timeSent":1631549626099,
  "username":"giorgos",
  "password":"myPassword123*"
}

LoginResponse

Response for LoginRequest. It contains a sessionId which identifies the opened Cirrus session for the current user.

{
  "messageType":"LoginResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "responseMessage":"Login completed successfully.",
  "timeSent":1631549626100,
  "sessionId":"1234"
}

PeeringRequest

Request message to Provision a Yanzi Gateway to an existing account. Can optionally contain a list of properties to be assigned to the Gateway and a position.

{
  "messageType":"PeeringRequest",
  "timeSent":1631549626100,
  "list":[
    {
      "resourceType":"PropertyDTO",
      "name":"timeZone",
      "value":"CEST"
    }
  ],
  "gatewayDid":"EUI64-0080E10300099999",
  "locationName":"My House",
  "accountNumber":"123456",
  "username":"allan@yanzi.se",
  "position":{
    "resourceType":"SamplePosition",
    "timeCreated":1631549626100,
    "sampleTime":1631549626100,
    "longitude":12345.678,
    "latitude":23456.789,
    "timeOfPosition":1448539086,
    "positionType":{
      "resourceType":"PositionType",
      "name":"latLongTimeFloor"
    },
    "floorLevel":4
  }
}

PeeringResponse

{
  "messageType":"PeeringResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626100,
  "location":{
    "resourceType":"LocationDTO",
    "timeCreated":1631549626101,
    "locationAddress":{
      "resourceType":"LocationAddress",
      "timeCreated":1631549626101,
      "locationId":"123456"
    },
    "timeModified":1631549626401,
    "accountId":"262478",
    "name":"Beach House",
    "gwdid":"EUI64-12411261342"
  },
  "peeringResponseCode":{
    "resourceType":"PeeringResponseCode",
    "name":"registerSuccess"
  }
}

PeriodicRequest

Request message used as a "heartbeat" technique to keep the connection between the client and the Yanzi Server alive. It can also be used to calculate thecommunication delays between client and Yanzi Server.

{
  "messageType":"PeriodicRequest",
  "timeSent":1631549626101
}

PeriodicResponse

Response for PeriodicRequest. It contains both the time at the client and the time at the Yanzi Server.

{
  "messageType":"PeriodicResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626101,
  "timeAtClient":1427704105,
  "timeAtServer":1427804105
}

RemoveUnitPropertyRequest

Request message used to remove a property from a unit. It contains the UnitAddress of the unit and the UnitProperty to be removed.

{
  "messageType":"RemoveUnitPropertyRequest",
  "timeSent":1631549626101,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626101,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  },
  "unitProperty":{
    "resourceType":"UnitProperty",
    "timeCreated":1631549626101,
    "name":"logicalName",
    "value":"My test name!"
  },
  "argumentList":[]
}

RemoveUnitPropertyResponse

Response for RemoveUnitPropertyRequest. Contain only the respective ResponseCode.

{
  "messageType":"RemoveUnitPropertyResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626102,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626102,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456",
    "serverDid":"EUI64-0080E10300012345"
  },
  "unitProperty":{
    "resourceType":"UnitProperty",
    "timeCreated":1631549626102,
    "name":"logicalName",
    "value":"My test name!"
  }
}

ServiceRequest

Request message used to check systems' (client and Yanzi Server) version compatibility. Usually used when setting up the communication channel. It contains the version of the system running on the client.

{
  "messageType":"ServiceRequest",
  "timeSent":1631549626102,
  "version":"1.8.57dev",
  "clientId":"client-550e8400-e29b"
}

ServiceResponse

Response for ServiceRequest. It contains the time at the Yanzi Server and the version of the system running in the Yanzi Server. In addition to this, it contains a ServiceDetailsDTO object.

{
  "messageType":"ServiceResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626103,
  "timeServer":1631549626103,
  "version":"1.8.57dev",
  "serviceDetails":{
    "resourceType":"ServiceDetailsDTO",
    "gatewayType":{
      "resourceType":"GatewayType",
      "name":"shrek"
    },
    "serverDid":"UUID-2663581AF30D4BD38F9ECD5BC97DC2EE",
    "loginState":{
      "resourceType":"LoginState",
      "name":"superUserCertificate"
    },
    "list":[
      {
        "resourceType":"AuthenticationServer",
        "name":"cop",
        "dnsname":"cop.yanzi.se",
        "description":"Yanzi Production authentication server"
      }
    ]
  }
}

SetCustomPropertyRequest

Request message used to set a property to a unit. It contains the LocationAddress of the location and the LocationProperty to be set.

{
  "messageType":"SetCustomPropertyRequest",
  "timeSent":1631549626103,
  "address":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626103,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456",
    "serverDid":"EUI64-0080E10300012345"
  },
  "property":{
    "resourceType":"CustomPropertyDTO",
    "timeCreated":1631549626103,
    "name":"_kira_department",
    "value":"Economy"
  }
}

SetCustomPropertyResponse

Response for SetLocationPropertyRequest.

{
  "messageType":"SetCustomPropertyResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626104,
  "address":{
    "resourceType":"LocationAddress",
    "timeCreated":1631549626104,
    "locationId":"123456",
    "serverDid":"EUI64-0090DAFFFF0040A9"
  },
  "property":{
    "resourceType":"CustomPropertyDTO",
    "timeCreated":1631549626104,
    "name":"_kira_department",
    "value":"RWNvbm9teQ=="
  }
}

SetPropertyRequest

Request message used to set a property. It contains the Address of the target and the LocationProperty to be set. Currently supports timeZone and locationType using a LocationAddress.

{
  "messageType":"SetPropertyRequest",
  "timeSent":1631549626104,
  "address":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626104,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456",
    "serverDid":"EUI64-0080E10300012345"
  },
  "property":{
    "resourceType":"PropertyDTO",
    "timeCreated":1631549626104,
    "name":"timeZone",
    "value":"CEST"
  }
}

SetPropertyResponse

Response for SetLocationPropertyRequest.

{
  "messageType":"SetPropertyResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626104,
  "address":{
    "resourceType":"LocationAddress",
    "timeCreated":1631549626104,
    "locationId":"123456",
    "serverDid":"EUI64-0090DAFFFF0040A9"
  },
  "property":{
    "resourceType":"PropertyDTO",
    "timeCreated":1631549626104,
    "name":"timeZone",
    "value":"PST"
  }
}

SetUnitPropertyRequest

Request message used to set a property to a unit. It contains the UnitAddress of the unit and the UnitProperty to be set. Only for single value properties.

{
  "messageType":"SetUnitPropertyRequest",
  "timeSent":1631549626105,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626105,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456"
  },
  "unitProperty":{
    "resourceType":"UnitProperty",
    "timeCreated":1631549626105,
    "name":"logicalName",
    "value":"My test name!"
  },
  "argumentList":[]
}

SetUnitPropertyResponse

Response for SetUnitPropertyRequest.

{
  "messageType":"SetUnitPropertyResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626105,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626105,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456",
    "serverDid":"EUI64-0080E10300012345"
  },
  "unitProperty":{
    "resourceType":"UnitProperty",
    "timeCreated":1631549626105,
    "name":"logicalName",
    "value":"My test name!"
  }
}

SetUserPropertyRequest

Request message used to set a property to a user. It contains the UserId of the target and the UserProperty to be set.

{
  "messageType":"SetUserPropertyRequest",
  "timeSent":1631549626106,
  "userProperty":{
    "resourceType":"UserProperty",
    "timeCreated":1631549626106,
    "name":"favorite",
    "value":{
      "resourceType":"UnitDTO",
      "timeCreated":1631549626106,
      "unitAddress":{
        "resourceType":"UnitAddress",
        "timeCreated":1631549626106,
        "did":"EUI64-0080E10300099999",
        "locationId":"123456",
        "serverDid":"EUI64-0080E10300012345"
      },
      "productType":"09876543210987",
      "lifeCycleState":{
        "resourceType":"LifeCycleState",
        "name":"shadow"
      },
      "isChassis":true,
      "chassisDid":"0999999999999",
      "unitTypeFixed":{
        "resourceType":"UnitType",
        "name":"inputMotion"
      },
      "unitTypeConfigured":{
        "resourceType":"UnitType",
        "name":"conferenceRoom"
      },
      "isNameSetByUser":true,
      "nameSetByUser":"Door's Motion",
      "defaultNameSetBySystem":"Motion-12AB",
      "userId":"giorgos@yanzi.se",
      "unitAcl":{
        "resourceType":"UnitAcl",
        "name":"operator"
      },
      "subunitIdentifier":0
    }
  },
  "userId":"test@yanzi.se"
}

SetUserPropertyResponse

Response to the SetUserPropertyRequest

{
  "messageType":"SetUserPropertyResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "timeSent":1631549626106,
  "userProperty":{
    "resourceType":"UserProperty",
    "timeCreated":1631549626106,
    "name":"favorite",
    "value":{
      "resourceType":"UnitDTO",
      "timeCreated":1631549626106,
      "unitAddress":{
        "resourceType":"UnitAddress",
        "timeCreated":1631549626106,
        "did":"EUI64-0080E10300099999",
        "locationId":"123456",
        "serverDid":"EUI64-0080E10300012345"
      },
      "productType":"09876543210987",
      "lifeCycleState":{
        "resourceType":"LifeCycleState",
        "name":"shadow"
      },
      "isChassis":true,
      "chassisDid":"0999999999999",
      "unitTypeFixed":{
        "resourceType":"UnitType",
        "name":"inputMotion"
      },
      "unitTypeConfigured":{
        "resourceType":"UnitType",
        "name":"conferenceRoom"
      },
      "isNameSetByUser":true,
      "nameSetByUser":"Door's Motion",
      "defaultNameSetBySystem":"Motion-12AB",
      "userId":"giorgos@yanzi.se",
      "unitAcl":{
        "resourceType":"UnitAcl",
        "name":"operator"
      },
      "subunitIdentifier":0
    }
  },
  "userId":"test@yanzi.se"
}

SubscribeData

Message used to asynchronously send data to the user without a prior individual request. SubscribeData are sent only to users that are subscribed to some data.

{
  "messageType":"SubscribeData",
  "timeSent":1631549626107,
  "list":[
    {
      "resourceType":"SampleList",
      "dataSourceAddress":{
        "resourceType":"DataSourceAddress",
        "timeCreated":1631549626107,
        "did":"EUI64-0080E10300099999-3-Humd",
        "locationId":"123456",
        "variableName":{
          "resourceType":"VariableName",
          "name":"relativeHumidity"
        },
        "instanceNumber":0
      },
      "timeCreated":1631549626107,
      "list":[
        {
          "resourceType":"SampleHumidity",
          "timeCreated":1631549626107,
          "sampleTime":1631549626107,
          "value":30.5,
          "temperature":296.45
        }
      ]
    }
  ]
}

SubscribeRequest

Request message used to set up a subscription to receive push messages. It requires a UnitAddress object and a SubscriptionType value. Currently the UnitAddress can contain just a locationId in order to subscribe to all messages in a location. Subscription to individual units is not currently supported.

{
  "messageType":"SubscribeRequest",
  "timeSent":1631549626107,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "locationId":"123456"
  },
  "subscriptionType":{
    "resourceType":"SubscriptionType",
    "name":"data"
  }
}

SubscribeResponse

SubscribeResponse message is sent as a reply to the SubscribeRequest message. It is used as an acknowledgement to the SubscribeRequest.

DEPRECATED: The responseMessage content of subscription expiration time, subscription type and location id is now deprecated as there are separate fields available for these data.

{
  "messageType":"SubscribeResponse",
  "responseCode":{
    "resourceType":"ResponseCode",
    "name":"success"
  },
  "responseMessage":"Subscribed to data for location 123456 until 1631564026108",
  "timeSent":1631549626108,
  "locationAddress":{
    "resourceType":"LocationAddress",
    "locationId":"123456"
  },
  "subscriptionType":{
    "resourceType":"SubscriptionType",
    "name":"data"
  },
  "expireTime":1631564026108
}

Enums

Enum AcceptState

Value Description
discovered Device has been discovered.
accepting Device is now being accepted to the system.
accepted Device has been succesfully accepted to the system.
failed Failed to accept device to the system.
removed Device has been suceessfully removed from the system.
blocked Device has been successfully blocked from the system.

Enum AssetState

Value Description
init In initialization state.
disabled In disabled state, will not work.
operational In operational state. Works as expected.
maintenance Undergoing maintenance. Not working.
armed In armed state.
armAfterInit In armed state after initialization.
breached In breached state
notify Notifying...
trigged In trigged stated.
occupied In occupied state. Asset in use.
free In free state. Asset free to use.
ok In ok state. Works as expected.
needService In need of service. Should undergo maintenance.
error Error occured.
missingInput Missing input from source.
connectionInstable Remote asset/chassis with unstable connection.
open In open state.
closed In closed state.
test In testing state.
full In full state.
almostFull In almost full state.
almostEmpty In almost empty state.
empty In empty state.
shadow Remote asset/chassis in unknown state, asset is not reacheable
present Remote asset/chassis in ok state, asset is reacheable
isMotion Motion sensor in motion state
isNoMotion Motion sensor in no motion state

Enum DataTransformation

Value Description
none No transformation, All samples stored are returned as is (DEFAULT)
points Samples are transformed into Points se MapToPoint.java
pointsChange Samples are transformed into points and then compressed by removing consecutive samples with same value
pointsTransition Same as pointsChange but additional samples are inserted 1ms before every transition

Enum DeviceAcceptState

Value Description
discovered Device was seen in the discovery process and is available to be accepted
accepting Decision to accept was made and now we wait for device to come back to be accepted
accepted Device was accepted and is now authenticated
failed Device failed to be accepted, maybe got accepted by someone else
removed Device was discovered a while ago but has not been heard from for some time
blocked Device that used to be authenticated but is now untrusted

Enum DeviceUpState

Value Description
up Device was up and is still up.
down Device was down and is still down.
goingUp Device was down but is now up.
goingDown Device was up but is now down.
estimatedGoingDownByGoingUp Device was going up but time of going down was unknown.
unknown Unknown state.

Enum EventType

Value Description
newUnAcceptedDeviceAccepted When the authentication of a new device is finished.
newUnAcceptedDeviceAccepting When the authentication of new device is in progress.
newUnAcceptedDeviceSeenByDiscovery When a location finds an unknown and unmanaged device.
newUnAcceptedDeviceAcceptFailed The accepting of the device failed.
remoteLocationGatewayIsNowDOWN LinkServer event when a LocationGateway disconnects.
remoteLocationGatewayIsNowUP LinkServer event when a LocationGateway connects.
physicalDeviceFirstData Physical device processed first data.

Enum FactoryDefaultType

Value Description
gateway Will Factory default a gateway with the provided address
device Will Factory default a device with the provided address
allDevices Will factory default all devices matching the provided address (will ignore the did field)

Enum LevelState

Value Description
empty Empty.
halffull Half full.
quarterfull Quarter full.
threquarterfull Three-quarters full.
percent10 10 percent full.
percent20 20 percent full.
percent30 30 percent full.
percent40 40 percent full.
percent50 50 percent full.
percent60 60 percent full.
percent70 70 percent full.
percent80 80 percent full.
percent90 90 percent full.

Enum LifeCycleState

Value Description
unAccepted Device is available to be accepted, but is unknown and untrusted.
accepting Decided to add the device and waiting for it to attach and communicate again.
shadow Device is not reachable, only historical data can be accessed.
seenByDiscovery Device is discovered normally, but we can not access it (yet?)
otherOwner Someone else is currently controlling the device
present Device fully operational and may be communicated with.
deleted Untrusted device and only historical data will be available
subUnit This is a unit that is a part of another device that defines a LifeCycleState. A subUnit state never changes.

Enum LoginState

Value Description
blocked Internal state. Please try again soon.
noCertificate Internal state. Please try again soon.
certificateInProgress Internal state. Please try again soon.
certificateInPlace Internal state. Please try again soon.
userDTOInPlace Internal state. Please try again soon.
accountDTOInPlace Internal state. Please try again soon.
singleAccountCertificate Internal state. Please try again soon.
superUserCertificate Service is ready and setup for multi-user access. This means that both username and password are needed to login.
normalUserCertificate Service is ready and setup for single-user access. This means that only password is needed to login.

Enum OpenClosedState

Value Description
open Open
closed Closed
unknown Unknown state

Enum OutputValue

Value Description
on The output is turned ON.
off The output is turned OFF.

Enum PeeringResponseCode

Value Description
notAdmin The user is not admin of the account that the peering was attempted for
locationNonExistent Gateway does not exist
inUse Gateway is in use
alreadyPeered Gateway already registered
requestSent Gateway is being registered, please wait
locationIdError Registration failed. Make sure all fields are correct and try again
registerFail Registration failed. Make sure all fields are correct and try again
registerSuccess Registration successful
oldVersion Gateway is running a too old version

Enum PositionType

Value Description
latLong latitude, longitude
latLongTime latitude, longitude, timeOfPosition
latLongAltitudeTime latitude, longitude, altitude, timeOfPosition
fullPosition latitude, longitude, altitude, timeOfPosition, floorLevel, accuracy, provider, isStatic.
latLongTimeFloor latitude, longitude, timeOfPosition, floorLevel

Enum PropertyName

Value Description
logicalName The logical name of a unit.
BIM The BIM Id of a unit
room The room number.
dataSource List of Data Source Ids
dataSink List of Data Sink Ids
timeZone TimeZone in which the unit is
zeroLevel Used to define a zeroLevel (or offset)
geoJSON String with JSON representation of geographic data
heightAboveFloor String indicating height above floor
objectThickness Used to define the thickness of an object in micrometers
locationType String indicating custom locationType
assetParentId Id of the parent in the asset hierarchy
activityLevel String with the activityLevel (e.g. high/medium/low)
countryCode Country in which the gateway is located

Enum ResponseCode

Value Description
success The request was processed normally (OK).
inProgress The request is in progress.
errorUnknown Unknown error occured.
errorNotFound The requested resource was not found
errorInvalidMessage The request was ignored as it was considered invalid.
errorAuthentication The request was ignored as authentication failed.
errorInvalidDestination The request was ignored as the destination is invalid.
errorChannelNotAvailable The request was ignored, no available channel.
errorUnsupportedRequest The request was ignored, this server does not implement it.
errorDestinationUnavailable The request was ignored, unable to forward request.
errorInternalMapperMissing The mapper is missing. Returning empty message.
errorUnknownMessage Unknown error message.
errorInvokingMessage Error invoking message.
errorSourceIsTransient Data unavailable source is transient without history

Enum SlotSize

Value Description
min10 10 minute time slot

Enum SubscriptionType

Value Description
data Data from sensors and occupancy/utilization data from Assets
config Updates when configuration has changed on a unit – e.g. a property is set
lifecycle Updates when a gateways or sensors lifecycle state changes
battery Battery information updates
sensorData Raw data originating from physical sensors, e.g temperature and humidity
assetData Gives data originating from physical sensors that belongs to (a source of) an Asset
occupancy Gives the occupancy (current occupancy state) and the utilization data of an Asset
occupancySlots Gives the same data as “occupancy” but data is based on a fix 10 minutes time slot. Slots are sent every 10 minutes
sensorSlots Gives the mean, min and max value over a fixed 10 min time slot. Slots are sent every 10 minutes
assetSlots Gives the mean, min and max value of “assetData” over a 10 min fixed time slot. Slots are sent every 10 minutes

Enum SystemUserAcl

Value Description
admin Administrator user, can edit all configuration and manage account users.
writer The user can control device outputs, but cannot alter configuration.
reader User is Read-only.

Enum UnitAcl

Value Description
administrator Administrator user
operator User with read and write rights.
viewer User with read only rights.
block Deny all access.
undefined Nothing.

Enum UnitAlarmSetValues

Value Description
arm Arms the alarm.
disable Disables the alarm.
trigg Triggers the alarm.
snooze Snoozes the alarm.
reset Resets the alarm.

Enum UnitType

Value Description
genericDevice Generic device
gateway Gateway
remoteGateway Remote gateway
temp Temperature sensor
distance Distance sensor
carbonDioxide Carbon Dioxide senson
energyMeter Energy meter senson
powerMeter Energy meter
inputMotion Motion senson
outputLamp Lamp
humidity Humidity sensor
camera Camera
asset Asset
facility Facility
floor Floor
room Room
recycleBin Recycle Bin
toilet Toilet
restroom Restroom
conferenceRoom Conference Room
chair Chair
desk Desk
building Building
spot Spot
area Area
areaGroup Group of Areas
zone Zone
snowMeter Snow Meter Sensor
stack Stack of things
washroom Washroom
cleaningRound Cleaning round
illuminance Ambient light sensor
soundPressureLevel Sound Pressure Level sensor
footfall Footfall counters
accelerometer Accelerometer sensor
gyro Gyrometer
pulseBand Pulse band
force Force sensor
dispenser Generic dispenser
dispenserSoap Soap dispenser
dispenserTowel Towel dispenser
dispenserGroup Group of dispensers
volatileOrganicCompound Volatile Organic Compound sensor

Enum VariableName

Value Description
temperatureC Temperature in Celsius
temperatureK Temperature in Kelvin
totalenergy Total Energy measured by unit (kWh)
totalApparentEnergy Total Energy measured by unit (kWh)
totalpower Measured total power consumption (W)
electricalPower Measured total power consumption (W)
totalpowerInst Calculated total power consumption (W)
relativeHumidity Relative humidity from a humidity sensor
carbonDioxide Carbon dioxide
counter Generic counter, number of counts
motion Shows changes or events such as a motion detector
distance Distance (mm)
percentage Percentage of source value
pressure Pressure (Pa)
volt Voltage (V)
heartRate Heart rate (bpm)
lampIntensity Intensity of a LED (values in range of 1-100)
unitState Unit state
assetUtilization Asset utilization sample
uplog UpState of a device. Eg. connected/disconnected
positionLog The physical position of a device
illuminance Illuminance (mlux)
soundPressureLevel Sound pressure level (mBA)
volatileOrganicCompound Volatile Organic Compound
openClosed Open/Closed state
siteOnlineStatus Site: Online/Offline/Troubled/Missing
particulateMatter Particals in the air

Resource DTOs

AcceptEntityDTO

AcceptEntityDTO represents the event of a device being accepted in the system.

{
  "resourceType":"AcceptEntityDTO",
  "timeCreated":1631549626129,
  "timeWhenAccepted":1428996894,
  "timeFirstSeen":1631549616129,
  "acceptState":{
    "resourceType":"DeviceAcceptState",
    "name":"discovered"
  },
  "acceptUserid":"giorgos@yanzi.se",
  "did":"EUI64-0080E10300099999",
  "productType":"0090DA12121212",
  "inetAddress":"178.45.224.13",
  "macAddress":"00-14-22-01-23-45",
  "gwdid":"EUI64-0080E10300012345",
  "locationId":"123456"
}

AccountDTO

AccountDTO object holds all information that can describe a Yanzi Account. It contains the account number, the account name, the owner name and the time that is was last modified.

{
  "resourceType":"AccountDTO",
  "timeCreated":1631549626130,
  "accountNumber":"156468",
  "accountName":"TestAccount",
  "timeModified":1427705889,
  "owner":"test@yanzi.se",
  "roles":[
    {
      "resourceType":"AccountUserRole",
      "userId":"test@yanzi.se",
      "systemUserAcl":{
        "resourceType":"SystemUserAcl",
        "name":"admin"
      }
    },
    {
      "resourceType":"AccountUserRole",
      "userId":"support@yanzi.se",
      "systemUserAcl":{
        "resourceType":"SystemUserAcl",
        "name":"reader"
      }
    }
  ],
  "admDomainId":"yanzi",
  "admDomainParentAccount":"15487"
}

AccountUserRole

Contains an Id of a user and a SystemUserAcl for the user with that Id.

{
  "resourceType":"AccountUserRole",
  "userId":"34572472",
  "systemUserAcl":{
    "resourceType":"SystemUserAcl",
    "name":"admin"
  }
}

CustomPropertyDTO

Object defining a CustomProperty. The name is an arbitrary string and the value is a Base64 encoded string

{
  "resourceType":"CustomPropertyDTO",
  "timeCreated":1631549626131,
  "name":"_my_custom_property",
  "value":"RWNvbm9teQ=="
}

DataSourceAddress

DataSourceAddress object is used to uniquely identify a source of samples.

{
  "resourceType":"DataSourceAddress",
  "timeCreated":1631549626131,
  "did":"EUI64-0080E10300099999-3-Humd",
  "locationId":"123456",
  "variableName":{
    "resourceType":"VariableName",
    "name":"relativeHumidity"
  },
  "instanceNumber":0
}

DataSourceDTO

DataSourceDTO is used to uniquely identify a DataSource. DataSourceDTO object holds all information that describe a data source. For example, the temp and the humidity sensors are two datasources that exist in a Yanzi Climate device. It contains a DataSource object, the SI Unit it is measured with and the time of generation.

{
  "resourceType":"DataSourceDTO",
  "timeCreated":1631549626131,
  "dataSourceAddress":{
    "resourceType":"DataSourceAddress",
    "timeCreated":1631549626131,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456",
    "serverDid":"EUI64-0080E10300012345",
    "variableName":{
      "resourceType":"VariableName",
      "name":"relativeHumidity"
    },
    "instanceNumber":5,
    "instanceName":"Humidity Source",
    "valueTypes":[
      {
        "resourceType":"ValueTypeDTO",
        "key":"humidity",
        "dataType":"number",
        "quantityKind":"humidity",
        "valueUnit":"%"
      },
      {
        "resourceType":"ValueTypeDTO",
        "key":"temperature",
        "dataType":"number",
        "quantityKind":"temperature",
        "valueUnit":"K"
      }
    ]
  },
  "siUnit":{
    "resourceType":"SiUnit",
    "name":"percent"
  }
}

ElectricalPhaseDTO

{
  "resourceType":"ElectricalPhaseDTO",
  "current":5.53,
  "power":1234.9,
  "voltage":239.7
}

EventDTO

EventDTO object holds all information that describe an event. For example, an event occurs when a new device is accepted in a system. The type of the event is mentioned in the EventType property. It contains a UnitAddress object, the time the event occured and a list of DTO objects.

{
  "resourceType":"EventDTO",
  "timeCreated":1631549626132,
  "timeOfEvent":1631549626132,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626132,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456",
    "serverDid":"EUI64-0080E10300012345"
  },
  "list":[
    {
      "resourceType":"AcceptEntityDTO",
      "timeCreated":1631549626132,
      "timeWhenAccepted":1428996894,
      "timeFirstSeen":1631549616132,
      "acceptState":{
        "resourceType":"DeviceAcceptState",
        "name":"discovered"
      },
      "acceptUserid":"giorgos@yanzi.se",
      "did":"EUI64-0080E10300099999",
      "productType":"0090DA12121212",
      "inetAddress":"178.45.224.13",
      "macAddress":"00-14-22-01-23-45",
      "gwdid":"EUI64-0080E10300012345",
      "locationId":"123456"
    }
  ],
  "eventType":{
    "resourceType":"EventType",
    "name":"physicalDeviceIsNowUP"
  }
}

LocationAddress

LocationAddress object is used to uniquely identify a location consisting of one or more sensors. It cointains the location id and the server id.

{
  "resourceType":"LocationAddress",
  "timeCreated":1631549626133,
  "locationId":"123456"
}

LocationDTO

LocationDTO object holds all information that describe a location. It contains a time of generation, a time of last modification, a LocationAddress object, a name, an account id, a gateway id and Yanzi Server id.

{
  "resourceType":"LocationDTO",
  "timeCreated":1631549626133,
  "locationAddress":{
    "resourceType":"LocationAddress",
    "timeCreated":1631549626133,
    "locationId":"123456"
  },
  "timeModified":1631549626433,
  "accountId":"262478",
  "name":"Beach House",
  "gwdid":"EUI64-12411261342"
}

MatchDTO

Object containing Name, Type and Value for a filtering based on the match.

{
  "resourceType":"MatchDTO",
  "timeCreated":1631549626133,
  "name":"lifeCycleState",
  "matchType":"equals",
  "value":"present"
}

MessageIdentifier

MessageIdentifier object is an optional parameter in every Cirrus message, and is used to track sent requests. Every response contains the same MessageIdentifier object as the request that caused it.

{
  "resourceType":"MessageIdentifier",
  "timeCreated":1631549626133,
  "messageId":"17"
}

PairDTO

Contains a Pair type-value, where the value is a Long.

{
  "resourceType":"PairDTO",
  "timeCreated":1631549626133,
  "valueType":"DispenserX",
  "value":5
}

PropertyDTO

Object defining a Property. Those properties are system defined by PropertyName and the value must be of the type defined in the corresponding PropertyName.

{
  "resourceType":"PropertyDTO",
  "timeCreated":1631549626134,
  "name":"timeZone",
  "value":"PST"
}

Range

The Range object is used to define a time period. It contains a start and an end point in time.

{
  "resourceType":"Range",
  "timeCreated":1631549626135,
  "timeStart":1631549326135,
  "timeEnd":1631549626135,
  "numberOfSamples":50
}

SampleAccelerometer

Sample that contains the information from an accelerometer sensor.

{
  "resourceType":"SampleAccelerometer",
  "timeCreated":1631549626185,
  "sampleTime":1631549626135,
  "valueX":12.34,
  "valueY":-23.45,
  "valueZ":34.56
}

SampleAsset

The SampleAsset object is used to represent a sample comming from an asset entity. It contains an AssetState and (optionally) a LevelState value.

{
  "resourceType":"SampleAsset",
  "timeCreated":1631549626135,
  "sampleTime":1631549626135,
  "assetState":{
    "resourceType":"AssetState",
    "name":"occupied"
  },
  "levelState":{
    "resourceType":"LevelState",
    "name":"percent90"
  }
}

SampleBattery

The SampleBattery contains the voltage measured in millivolts (mV) as a value and the corresponding percentage of battery left.

{
  "resourceType":"SampleBattery",
  "sampleTime":1631549626135,
  "value":2890,
  "percentFull":87
}

SampleCO2

The SampleCO2 object is used to represent a sample generated from a CO2 sensor. The value is reported in ppm(eg. 567ppm of CO2).

{
  "resourceType":"SampleCO2",
  "sampleTime":1631549626136,
  "value":567
}

SampleDistance

The SampleDistance object is used to represent a sample containing a distance value. This value is measured in mm(eg. 1234mm).

{
  "resourceType":"SampleDistance",
  "sampleTime":1631549626136,
  "value":1234
}

SampleElectrical

{
  "resourceType":"SampleElectrical",
  "sampleTime":1631549626136,
  "totalEnergy":23428465,
  "totalPower":23434.34,
  "frequency":50,
  "powerFactor":0.94,
  "phases":[
    {
      "resourceType":"ElectricalPhaseDTO",
      "current":3.23,
      "power":342,
      "voltage":100
    }
  ]
}

SampleElectricalEnergySimple

The SampleElectricalEnergySimple object contains a sample generated from a general output device. It always contains the value of the totalEnergy consumed by the device expressed in mWs and the instant power expressed in W. It may also contain the voltage of the line expressed in mV, the current intensity expressed in mA, the total amount of apparent energy expressed in mWs and the total amount of time expressed in ms that the instant power has been above 25W.

{
  "resourceType":"SampleElectricalEnergySimple",
  "sampleTime":1631549626137,
  "totalEnergy":23428465,
  "instantPower":240,
  "lineVoltage":20,
  "lineCurrent":12,
  "totalApparentEnergy":3745,
  "timeDraining":3947934575
}

SampleEndOfSlot

The SampleEndOfSlot object is used to represent the last sample received during an slot (time interval) it contains a slotSize that defines that interval size and the mentioned sample.

{
  "resourceType":"SampleEndOfSlot",
  "timeCreated":1631549626137,
  "sampleTime":1631549626137,
  "slotSize":{
    "resourceType":"SlotSize",
    "name":"min10"
  },
  "sample":{
    "resourceType":"SampleAsset",
    "timeCreated":1631549626137,
    "sampleTime":1631549626137,
    "assetState":{
      "resourceType":"AssetState",
      "name":"occupied"
    },
    "levelState":{
      "resourceType":"LevelState",
      "name":"percent90"
    }
  }
}

SampleFootfall

SampleFootfall contains information about the main counter of a Footfall camera. The main value (value) is the ingress counter and the sample also contains the egress counter.

{
  "resourceType":"SampleFootfall",
  "timeCreated":1631549626137,
  "sampleTime":1631549626137,
  "value":100,
  "egress":50
}

SampleForce

The SampleForce object is used to represent a sample containing force in milliNewtons (eg. 9800 mN).

{
  "resourceType":"SampleForce",
  "sampleTime":1631549626137,
  "value":19600
}

SampleHumidity

The SampleHumidity ojbect is used to represent a sample containing humidity value in percentage (0-100). Optionally it can contain also a temperature value expressed in Kelvins.

{
  "resourceType":"SampleHumidity",
  "sampleTime":1631549626138,
  "value":30.5,
  "temperature":296.45
}

SampleIlluminance

The SampleIlluminance object is used to represent a sample containing illuminance in mlux (eg. 567000 mlux). If supported by the sensor element, it will also contain the colorTemperature in K (eg. 5725 K).

{
  "resourceType":"SampleIlluminance",
  "sampleTime":1631549626138,
  "value":567000,
  "colorTemperature":5725
}

SampleImageTime

{
  "resourceType":"SampleImageTime",
  "timeCreated":1631549626138,
  "sampleTime":1631549626138,
  "dimensions":"600x480",
  "size":288000,
  "format":"jpg"
}

SampleLamp

The SampleLamp object contains a sample created from a Yanzi LED. It contains a value indicating the percentage of intensity of the lamp (0 off - 100 totally on) and a counter indicating how many times the lamp has been switched.

{
  "resourceType":"SampleLamp",
  "timeCreated":1631549626138,
  "sampleTime":1631549626138,
  "value":50,
  "counter":45
}

SampleMotion

Sample for describing the state of a Motion device. The value indicates the number of times that motion has been detected since the node last boot and increments for every motion. timeLastMotion indicates the Time of the last motion in ms since epoch.

{
  "resourceType":"SampleMotion",
  "timeCreated":1631549626139,
  "sampleTime":1631549626139,
  "value":47,
  "timeLastMotion":1451647857000
}

SampleOnOff

The SampleOnOff object represents the state of a source that can either be on (true) or off (false). It contains an optional toggle counter.

{
  "resourceType":"SampleOnOff",
  "timeCreated":1631549626139,
  "sampleTime":1631549626139,
  "value":{
    "resourceType":"OutputValue",
    "name":"off"
  },
  "counter":123
}

SampleOpenClosed

The SampleOpenClosed object represents the state of a source that can either be open, closed or in an unknown state. It also contains the time of the last state change. It contains an optional open counter and an optional closed counter.

{
  "resourceType":"SampleOpenClosed",
  "sampleTime":1631549626139,
  "value":{
    "resourceType":"OpenClosedState",
    "name":"closed"
  },
  "timeLastChange":1631546026139
}

SamplePercentage

The SamplePercentage object is used to represent a sample containing a percentage.

{
  "resourceType":"SamplePercentage",
  "timeCreated":1631549626139,
  "sampleTime":1631549626139,
  "value":56
}

SamplePosition

The SamplePosition object is used to represent a sample containing a position of an entity.

{
  "resourceType":"SamplePosition",
  "timeCreated":1631549626140,
  "sampleTime":1631549626140,
  "longitude":12345.678,
  "latitude":23456.789,
  "timeOfPosition":1448539086,
  "positionType":{
    "resourceType":"PositionType",
    "name":"latLongTimeFloor"
  },
  "floorLevel":4
}

SamplePressure

The SamplePressure object is used to represent a sample containing pressure in Pa (eg. 101300 Pa).

{
  "resourceType":"SamplePressure",
  "sampleTime":1631549626140,
  "value":101300
}

SampleSoundPressureLevel

The SampleSoundPressureLevel object is used to represent a sample containing sound pressure in mBA (milli Bell A-rated). The main value is the average sound pressure level during the measured inteval. It also contains the min and the max value observed during that interval and the corresponding SampleStatus that will indicate if measured values are outside the limits.

{
  "resourceType":"SampleSoundPressureLevel",
  "sampleTime":1631549626140,
  "value":5670,
  "max":5720,
  "min":5665,
  "statusMax":{
    "resourceType":"SampleStatus",
    "name":"greaterThan"
  },
  "statusMin":{
    "resourceType":"SampleStatus",
    "name":"ok"
  },
  "statusValue":{
    "resourceType":"SampleStatus",
    "name":"ok"
  }
}

SampleStack

Contains the quantity of elements in a stack.

{
  "resourceType":"SampleStack",
  "sampleTime":1631549626140,
  "value":22
}

SampleString

The SampleString object is used to represent a sample that contains a value that is a string.

{
  "resourceType":"SampleString",
  "timeCreated":1631549626141,
  "sampleTime":1631549626141,
  "sampleValue":"Test sample text."
}

SampleTemp

SampleTemp object is used to represent a sample containing temperature value.

{
  "resourceType":"SampleTemp",
  "timeCreated":1631549626141,
  "sampleTime":1631549626141,
  "value":296.6
}

SampleUpState

Sample used to indicate the UpState of a device. Eg. connected/disconnected

{
  "resourceType":"SampleUpState",
  "timeCreated":1631549626141,
  "sampleTime":1631549626131,
  "deviceUpState":{
    "resourceType":"DeviceUpState",
    "name":"up"
  },
  "opaque":"non-transparent"
}

SampleUtilization

The SampleUtilization object contains utilization information of an asset. It indicates the number of child assets in free, occupied or other state (missingInput, unknown, etc.)

{
  "resourceType":"SampleUtilization",
  "timeCreated":1631549626141,
  "sampleTime":1631549626141,
  "free":15,
  "occupied":20,
  "other":3
}

SampleVOC

The SampleVOC object is used to represent a sample generated from a Volatile Organic Compound sensor. The value is reported in ppb(eg. 122 parts per billion).

{
  "resourceType":"SampleVOC",
  "sampleTime":1631549626142,
  "value":122,
  "equivalentCO2":540
}

SampleWeight

SampleWeight object is used to represent a sample containing weight value. The value it contains is expressed in kilograms (kg).

{
  "resourceType":"SampleWeight",
  "timeCreated":1631549626142,
  "sampleTime":1631549626142,
  "value":12.34
}

ServiceDetailsDTO

Contains information regarding the service provided.

{
  "resourceType":"ServiceDetailsDTO",
  "gatewayType":{
    "resourceType":"GatewayType",
    "name":"shrek"
  },
  "serverDid":"UUID-2663581AF30D4BD38F9ECD5BC97DC2EE",
  "loginState":{
    "resourceType":"LoginState",
    "name":"superUserCertificate"
  },
  "list":[
    {
      "resourceType":"AuthenticationServer",
      "name":"cop",
      "dnsname":"cop.yanzi.se",
      "description":"Yanzi Production authentication server"
    }
  ]
}

SlotDTO

The object contains the information about sensor values over a time period. The time period is defined by the SlotSize. It contains information about the min, max, sum (called aggregateValue) and the number of samples which the sum is based on over the time period. The aggregateValue is the sum of the sample values. The maxValueTime is the time of the sample containing the max value. the minValueTime is the time of the sample containing the min value.

{
  "resourceType":"SlotDTO",
  "timeCreated":1631549626142,
  "sampleTime":1631549626142,
  "maxValue":36.1,
  "maxTime":1631549026142,
  "minValue":35.234,
  "minTime":1631549626142,
  "aggregateValue":107.334,
  "numberOfValues":3,
  "slotSize":{
    "resourceType":"SlotSize",
    "name":"min10"
  }
}

UnitAddress

UnitAddress object is used to identify a unique unit. It contains a did, a locationId and a serverDid.

{
  "resourceType":"UnitAddress",
  "timeCreated":1631549626143,
  "did":"EUI64-0080E10300099999",
  "locationId":"123456"
}

UnitDTO

UnitDTO object holds all information that describe a Yanzi unit. For example, the temp and the humidity sensors are two units that exist in a Yanzi Climate device. It contains a DataSource object, the SI Unit it is measured with and the time of generation.

{
  "resourceType":"UnitDTO",
  "timeCreated":1631549626143,
  "unitAddress":{
    "resourceType":"UnitAddress",
    "timeCreated":1631549626143,
    "did":"EUI64-0080E10300099999",
    "locationId":"123456",
    "serverDid":"EUI64-0080E10300012345"
  },
  "productType":"09876543210987",
  "lifeCycleState":{
    "resourceType":"LifeCycleState",
    "name":"shadow"
  },
  "isChassis":true,
  "chassisDid":"0999999999999",
  "unitTypeFixed":{
    "resourceType":"UnitType",
    "name":"inputMotion"
  },
  "isNameSetByUser":true,
  "nameSetByUser":"Door's Motion",
  "defaultNameSetBySystem":"Motion-12AB",
  "userId":"giorgos@yanzi.se",
  "unitAcl":{
    "resourceType":"UnitAcl",
    "name":"operator"
  },
  "subunitIdentifier":0
}

UnitProperty

PropertyDTO specific for indicating a Unit property.

{
  "resourceType":"UnitProperty",
  "timeCreated":1631549626143,
  "name":"logicalName",
  "value":"Conference Room Orange"
}

UserDTO

UserDTO object holds all information that describe a user.

{
  "resourceType":"UserDTO",
  "timeCreated":1631549626143,
  "yanziId":"alan@smith.com",
  "firstName":"Alan",
  "lastName":"Smith",
  "streetAddress":"Vagen 123",
  "postalCode":"55133",
  "city":"Stockholm",
  "country":"Sweden"
}

UserProperty

PropertyDTO specific for indicating a User property.

{
  "resourceType":"UserProperty",
  "timeCreated":1631549626144,
  "name":"favorite",
  "value":{
    "resourceType":"UnitDTO",
    "timeCreated":1631549626144,
    "unitAddress":{
      "resourceType":"UnitAddress",
      "timeCreated":1631549626144,
      "did":"EUI64-0080E10300099999",
      "locationId":"123456",
      "serverDid":"EUI64-0080E10300012345"
    },
    "productType":"09876543210987",
    "lifeCycleState":{
      "resourceType":"LifeCycleState",
      "name":"shadow"
    },
    "isChassis":true,
    "chassisDid":"0999999999999",
    "unitTypeFixed":{
      "resourceType":"UnitType",
      "name":"inputMotion"
    },
    "isNameSetByUser":true,
    "nameSetByUser":"Door's Motion",
    "defaultNameSetBySystem":"Motion-12AB",
    "userId":"giorgos@yanzi.se",
    "unitAcl":{
      "resourceType":"UnitAcl",
      "name":"operator"
    },
    "subunitIdentifier":0
  }
}
Back to top