This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Getting Started

The journey of integrating with iZone begins here.

1: Before you begin
2: Local network integration

2.1: Discovery
2.2: Query
2.3: Control
2.4: Documents & Tools

3: Cloud integration

3.1: Authorization
3.2: Discovery
3.3: Query
3.4: Control
3.5: Event Report
3.6: Result

1 - Before you begin

Prerequisites before getting your hands dirty.

You will need to have an iZone system before starting your integration. We recommand the following:

Make sure the firmware of all the iZone devices have been updated to the latest stable versions.

iZone system should be properly installed and configured.

The iZone Home mobile application can communicate successfully with the iZone system both locally and remotely.

Having issues with installation?

Use iZonepedia to search for diagrams, step-by-step instructions and answers to all your technical problems.

2 - Local network integration

Use your local area network (LAN) to integrate with an iZone system.

2.1 - Discovery

Make requests to discover local iZone devices.

Discover Local Device Command

Send IASD to UDP Broadcast 255.255.255.255:12107

An expected iZone bridge response would be like ASPort_12107,Mac_[bridge_ID],IP_[bridge_IPAddr],...

If the response is:

ASPort_12107,Mac_xxxxxxxxx,IP_xxx.xxx.xxx.xxx
ASPort_12107,Mac_xxxxxxxxx,IP_xxx.xxx.xxx.xxx,iZone, …

Then this device only supports the original API, which is described in this document

If the response is:

ASPort_12107,Mac_xxxxxxxxx,IP_xxx.xxx.xxx.xxx,iZoneV2, …

Then this device also supprts the new API, described below. The support for the original API is maintained.

Example response:

ASPort_12107,Mac_XXXXXXXXX,IP_xxx.xxx.xxx.xxx,iZoneV2,iLight,iDrate,iPower,Split

Where:

XXXXXXXXXX - is a 9-digit unique system ID number
iZone - iZone air con support API v1 (described in in this document)
iZoneV2 - iZone air con support API v2
iLight - lighting system, garage doors etc
iDrate - irrigation system,
iPower - monitoring system (power, air quality, solar diverter)
Split - split system air con

If a device does not support one of the above systems, the corresponding string will be replaced by “X” or missing

2.2 - Query

Make requests to query local iZone device states.

Query Local Device States Command

HTTP Request.

POST http://[bridge_IPAddr]/iZoneRequestV2

Request Body JSON:

{
    "iZoneV2Request": {
        "Type": 1,
        "No": 0,
        "No1": 0
    }
}

An example of response would be like:

{
    "AirStreamDeviceUId": string_deviceID,
    "DeviceType": "ASH",
    "SystemV2": datagram_systemsettings
}

where:

string_deviceID is 9-digits bridgeID get in discovery
datagram_systemsetting is datagram of an iZone device.

Refer to Reference the detail datagram of different types of iZone components.

2.3 - Control

Make requests to control local iZone device.

Control Local Device Command

HTTP Request.

POST http://[bridge_IPAddr]/iZoneCommandV2

Request Body JSON:

{
  "SysOn":type_syson
}

where:

type_syson is target value of command.

An expected response would be like:

OK

Refer to Reference the detail control actions dictionary of different types of iZone device control.

2.4 - Documents & Tools

Latest released documents & testing tools.

iZone API Document v2

iZone_JSON_datastrings.h v1.20

iZone Local API Test Example

Import this test example script iZoneExample.postman.json to Postman API Tools. Change IP address to your own testing system’s IP before start testing.

iZone API Document v1

iZone Ethernet Interface v1

3 - Cloud integration

Use iZone’s Cloud API to integrate with an iZone system.

Developer Account

You will need to have a developer account and get developer credentials to authenticate your integration on iZone.

To get a developer credential key, login developer account and your developer credential should display.

3.1 - Authorization

Get access token for calling iZone Cloud API.

iZone Cloud API uses OAuth access token to authorize user access.

Get authorization code

At some stage, you have to send user to iZone worldwide login service with your developer key and parameters.

Authorization Endpoint: https://worldwide.izone.com.au/login

The request uses GET method, with parameters:

Query Parameter
client_id	Your developer key
scope	Use `query-control`
state	A value you can used to track the session in redirect callback
response_type	Use `code` for authorization code
redirect_uri	Encoded URL matching for your developer account

The login service asks the user to authorize your integration to use their iZone system. The user authenticates with login their worldwide account. iZone sends an authorization code back to your integration.

Get access token

Once you get an authorization code, use it to get an access token and refresh token.

Token Endpoint: https://worldwide.izone.com.au/token

The request uses POST method, with parameters:

Query Parameter
client_id	Your developer key
grant_type	Use `authorization_code`
code	The authorization code received previously

If request format and parameters are all good, the response would be HTTP 200 OK, with payload like this:

{
  "access_token": "c3cda13u-393a-c832-112-946106e5bbab",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "c3cda13u-393a-c832-112-946106e5bbab",
  "scope": "query-control"
}

Use Access Token

The access token is required in every iZone Cloud API call. According to different types of iZone Cloud APIs:

HTTPS API
- Use “Bearer” authentication in headers. Authorization: Bearer access-token
gRPC API
- Use “accessToken” in gPRC proto.

3.2 - Discovery

Make requests to discover user’s iZone devices.

Discover Device Command

HTTPS Request.

POST https://api.izone.com.au/dev

Request Body JSON:

Key	Type	Description
requestId	string	A UUID string to identify request session
requestType	string	Must be `Discover`

An example of response would be like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "requestType": "Discover",
  "response": {
    "userID":string_userID,
    "devices":[
    {
        "componentId":"123456798_izone_systemsettings_0",
        "datagram":{
            "SysOn":1,
            "SysMode":2,
            "SysFan":3,
            ...
        }
    },
    ...]
}

Response contains requesting user’s string_userID and an array of all componentIds and their latest datagram.

Individual device states can be queried through Query.

Refer to Reference the detail datagram of different types of iZone components.

3.3 - Query

Make requests to query iZone device states.

Query Device States Command

HTTPS Request.

POST https://api.izone.com.au/dev

Request Body JSON:

Key	Type	Description
requestId	string	A UUID string to identify request session
requestType	string	Must be `Query`
componentId	string	A componentId to identify an iZone component

An example of response would be like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "requestType": "Query",
  "response": {
    "component":{
      "componentId":"123456798_izone_systemsettings_0",
      "datagram":{
          "SysOn":1,
          "SysMode":2,
          "SysFan":3,
          ...
      }
    }
  }
}

Where response is componentId:componentDatagram

Refer to Reference the detail datagram of different types of iZone components.

3.4 - Control

Make requests to control iZone device.

Control Device Command

HTTPS Request.

POST https://api.izone.com.au/dev

Request Body JSON:

Key	Type	Description
requestId	string	A UUID string to identify request session
requestType	string	Must be `Control`
componentId	string	A componentId to identify an iZone component
requestBody	json	A JSON control command body

An example of request body would like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "componentId": "123456798_izone_systemsettings_0",
  "requestType": "Control",
  "requestBody": {
    json_controlCommand
  }
}

where json_controlCommand is the one of control commands with target value.

An expected response would be like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "componentId": "123456798_izone_systemsettings_0",
  "requestType": "Control",
  "response": {
    "result":"OK"
  }
}

Refer to Reference the detail control actions dictionary of different types of iZone device control.

3.5 - Event Report

Get notified when device states changed.

Event Report API

iZone Cloud provides event report service, which can notify your event API when iZone device states changed or user deleted their account.

Please talk to Smart Alec about details of your event API.

Sync Request Body JSON Format:

Key	Type	Description
requestId	string	A UUID string to identify request session
requestType	string	Must be `Sync`
userId	string	A userId to identify an iZone worldwide user

An example of requesting re-discover/refresh would like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "userId": string_userID,
  "requestType": "Sync",
}

This request notifies user string_userID’s account condition has changed. To re-discover the user’s devices of userID.

Event Report Body JSON Format:

Key	Type	Description
requestId	string	A UUID string to identify request session
requestType	string	Must be `Event`
requestBody	json	A JSON datagram contains one or multiple devices datagram

An example of device event update would like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "requestType": "Event",
  "requestBody": {
    "devices":[
      {
        "componentId":"123456798_izone_systemsettings_0",
        "datagram":{
            "SysOn":1,
            "SysMode":2,
            "SysFan":3,
            ...
        }
      },
      ...
    ]
  }
}

where json_datagram is the one of iZone device datagram.

Refer to Reference the detail control actions dictionary of different types of iZone device control.

3.6 - Result

Get result.

Result Messages

iZone Cloud would return message after API actions are called.

An example of result would be like:

{
  "requestId": "28d45cb2-ff5a-4d58-a4c8-efb751ded699",
  "response": {
    "result":message_string
  }
}

where message_string contains OK or error messages.