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

Return to the regular view of this page.

Guide

1: Overview

2: Getting Started

2.1: Before you begin
2.2: Local network integration

2.2.1: Discovery
2.2.2: Query
2.2.3: Control
2.2.4: Documents & Tools

2.3: Cloud integration

2.3.1: Authorization
2.3.2: Discovery
2.3.3: Query
2.3.4: Control
2.3.5: Event Report
2.3.6: Result

3: Examples

4: Reference

4.1: AC Unit
4.2: Zone
4.3: Schedule
4.4: Irrigation
4.5: Power Monitor
4.6: Result Message

This guide contains all the information a developer need to understand and successfully integrate iZone into another system.

1 - Overview

Let’s talk about how an iZone system integrates with the outside world.

What is iZone?

Briefly, iZone is an engineering designed embedded system, which controls ducted air conditioning, zoning control devices and tons of other smart home devices.

How to integrate with an iZone system?

An iZone system communicates with the outside world through a device called an iZone “bridge”. A bridge must be connected to an IP network. There are two way of communicating with an iZone system via the bridge

Via local network: A client can call a local API hosted on the iZone bridge if they are located on the same local area network (LAN). This will faciliate faster communication and an internet connection is not needed.
Via cloud API: A cloud API is also available for a remote client access or cloud integration. The iZone bridge must be connected to the Internet to facilitate this connection.

Getting started

Local Network Integration: Path to control iZone from LAN.
Cloud Integration: Path to control iZone via Cloud APIs.

2 - Getting Started

The journey of integrating with iZone begins here.

2.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.2 - Local network integration

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

2.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.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.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.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

2.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.

2.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.

2.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.

2.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.

2.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.

2.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.

2.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.

3 - Examples

See your project in action!

Control4

There is an iZone driver for Control4 interface.

Home Assistant

One of our customers (Dr. Penny Wood) has developed an iZone integration for Home Assistant.

4 - Reference

Reference documents for iZone APIs.

Categoried by device type

4.1 - AC Unit

Local Entry Point

Local request entry point for iZone Aircon System is:

Query Request.

POST http://[bridge_IPAddr]/iZoneRequestV2

Control Request.

POST http://[bridge_IPAddr]/iZoneCommandV2

Local Query Request Format

Local query request body format for iZone Aircon System is:

Request Body JSON:

{
    "iZoneV2Request": {
        "Type": 1,                  //AC unit info - 1, Zone status - 2, Schedule - 3.
        "No": 0,                    //index number of zone or schedule
        "No1": 0                    //reserved
    }
}

Datagram

Systemsettings

{
    "SysOn": int,					// AC system on: SysOn_e
    "SysMode": int,					// AC system mode: SysMode_e
    "SysFan": int,					// AC system fan: SysFan_e
    "SleepTimer": int,				// number of minutes to set the timer for, 0 = timer off
    "Supply": int,					// supply air temperature (x100)
    "Setpoint": int, 				// unit setpoint temperature (x100)
    "Temp": int,					// return air temperature (x100)
    "RAS": int,						// return air sensor mode: ReturnAirSensor_e
    "CtrlZone": int,				// zone number to control the unit 0-13, if 15, the use unit setpoint.
    "Tag1": string,					// first line text
    "Tag2": string,					// second line text
    "Warnings": "none",				// indicates current warnings/errors: "none", "filter"
    "ACError": string,				// 3 character error code. (" OK" = no error)
    "EcoLock": int,					// if true, setpoints (zones and system) can only be set within EcoMax and EcoMin
    "EcoMax": int,					// maximum setpoint temperature if EcoLock = true (x100)
    "EcoMin": int,					// minimum setpoint temperature if EcoLock = true (x100)
    "NoOfConst": int,				// number of constants in the system
    "NoOfZones": int,				// number of zones in the system
    "SysType": int,					// system type, 310 requires supprot for unit control related functions, 210 no unit control
    "iSaveEnable": int,
    "iSaveOn": int,
    "LockCode": string,				// up to 6 digits
    "LockStatus": int,				// locked flag, 1 - unit locked. Enter keycode on iZone controller to unlock the system"
    "LockOn": int,					// lock enabled
    "FanAutoEn": int,				// fan auto mode enabled
    "FanAutoType": int,				// fan auto mode fan type: FanAutoType_e
    "FanCapacity": int,				// fan auto mode fan capacity (airflow)
    "FanUnitCapacity": int,			// fan auto mode unit capacity
    "FilterWarn": int,				// filter wanrning setting (months)
    "iZoneOnOff": int,				// iZone controls AC unit on/off function, 0 - disabled, 1 - enabled
    "iZoneMode": int,				// iZone controls AC unit mode function,  0 - disabled, 1 - enabled
    "iZoneFan": int,				// iZone controls AC unit fan function, 0 - disabled, 1 - enabled
    "iZoneSetpoint": int,			// iZone controls AC unit setpoint function, 0 - disabled, 1 - enabled
    "ExtOnOff": int,				// AC unit controls iZone on/off function, 0 - disabled, 1 - enabled
    "ExtMode": int,					// AC unit controls iZone mode function, 0 - disabled, 1 - enabled
    "ExtFan": int,					// AC unit controls iZone fan function, 0 - disabled, 1 - enabled
    "ExtSetpoint": int,				// AC unit controls iZone setpoint function, 0 - disabled, 1 - enabled
    "DamperTime": int,				// damper time setting (senconds), 0 - automatic
    "AutoOff": int,					// auto off enable, 0 - disabled, 1 - enabled
    "RoomTempDisp": int,			// display room temperature,  0 - disabled, 1 - enabled
    "RfCh": int,					// RF channel number (1-8)
    "AutoModeDeadB": int,			// auto mode deadband (x100)
    "WiredLeds": int,				// wired sensor leds setting 
    "AirflowLock": int,
    "AirflowMinLock": int,
    "OutOfViewRAS": int,
    "CpuType": int,					// AcCpuType_e
    "SysNo": int,					// 0 - 4
    "AcUnitBrand": int,				// type of the connected AC unit: UnitBrand_e
    "AcUnitBrandSet": int,			// type of the connected AC unit: UnitBrandSet_e
    "OemMake": int,					// system make: OemMake_e
    "HideInduct": int, 				// hide induct temperature setting
    "ReverseDampers":1,				// reverse dampers, 0 - disabled, 1 - enabled
    "Scrooge":0,					// scrooge mode, 0 - disabled, 1 - enabled
    "Pass":string,					// system configuration password
    "CnstCtrlAreaEn": int,			// enable the function, 0 - disabled, 1 - enabled
    "CnstCtrlArea": int,			// zone area setting for the constant control by area setting
    "StaticP": int,					// static pressure setting for Midea type of units 0-lowest -> 4-highest
    "OpenDampersWhenOff": int,		// open dampers when AC system is off setting
    "ShowActTemps": int,			// in the modern zone list show actual temperatures instead of airflow
    "UseInductEnergy": int,			// use induct energy setting
    "UnitOpt": {
        "RA":0,						// display RA sensor option, 0 - disabled, 1 - enabled
        "Master":1,					// display Master sensor option, 0 - disabled, 1 - enabled
        "Zones":1,					// display Zones sensor option, 0 - disabled, 1 - enabled
        "History":0,				// display unit history option, 0 - disabled, 1 - enabled
        "SlaveOpt":0				// display Master/Slave options, 0 - disabled, 1 - enabled
    },
    "Temperzone": {
        "HeatSetpoint": int,		// temperzone AC unit heat mode setpoint
        "CoolSetpoint": int,		// temperzone AC unit cool mode setpoint
        "FanType": int,
        "ModeType": int,
        "Quiet": int,				// temperzone outdoor fan quiet mode
    },
    "GasHeat": {
        "Type": int, 				// universal unit type control: GasHeatType_e
        "MinRunTime": int,			// minimum run time setting
        "AnticycleTime": int,		// anticycle time setting
        "StageOffset": int,			// stage offset setting
        "StageDelay": int,			// stage delay time setting
        "CycleFanCool": int,		// cycle fan in cool mode
        "CycleFanHeat": int,		// cycle fan in heat mode
    },
    "Ventilation":
    {
        "RhSetpoint":int,			// RH setpoint (5 - 95%)
        "VocsSetpoint":int,			// VOCs setpoint (50 - 2500ppb)
        "Eco2Setpoint":int,			// ECO2 setpotin (500 - 1500ppm)
        "FanStageDelay":int,		// fan stage delay in minutes (3 - 240m)
        "CycleFanOff":int,			// cycle fan off setting (0 - 1)
        "UseRhControl":int,			// use RH control setting (0 - 1)
        "UseVcosControl":int,		// use VOCs control setting (0 - 1)
        "UseEco2Control":int		// use ECO2 control setting (0 - 1)
    },
    "Coolbreeze":
    {
        "FanSpeed":int,				// current fan speed (1 - 100)
        "State":string,				// just a string to display
        "RhSet":int,				// humidity setpoint (10 - 90)
        "RhRead":int,				// humidity reading (%)
        "FanRunH":int,				// fan run hours
        "PumpRunH":int,				// pump run hours
        "PrewEn":int,				// prewash enable (0 - 1)
        "PrewTime":int,				// prewash time (1 - 60 minutes)
        "DrAfPrewEn":int,			// drain after prewash (0 - 1)
        "DrCycEn":int,				// drain cycle enable (0 - 1)
        "DrCycPer":int,				// drain cycle period (1 - 50 hours) send and receive number in minutes
        "PostwEn":int,				// post wash enable (0 - 1)
        "DrBfPostwEn":int,			// drain before post wash (0 - 1)
        "PostwT":int,				// post wash time (5 - 30 minutes)
        "Inverter":int,				// inverter (0 - 1)
        "ResumeLast":int,			// resume last state (0 - 1)
        "FanMaxAuto":int,			// maximum fan speed in auto mode (1 - 100)
        "FanMax":int,				// maximum fan speed in manual mode (1 - 100)
        "ExhMax":int,				// maximum fan speed in exhaust mode (1 - 100)
        "ExhEn":int,				// exhaust mode enable (0 - 1)
        "CtrlSens":int,				// control sensor (CoolbreezeControlSensor_e)
        "CalibTemp":int,			// temperature calibration (-50 - 50) /10 to get value
        "DeadTemp":int,				// temperature dead band (100 - 500) /100 to get value
        "AutoFanMaxTime":int		// Auto mode fan max speed time (0 - 60 minutes)
    }
}

Message	Type	Description
OK	Success	API called successfully
InvalidRequest	Error	Request format is incorrect
InvalidUser	Error	Request user token is invalid
UserNotAllowed	Error	Request user is not allowed for the operation
Error	Error	General error for other reasons

Guide

1 - Overview

What is iZone?

How to integrate with an iZone system?

Getting started

2 - Getting Started

2.1 - Before you begin

Having issues with installation?

2.2 - Local network integration

2.2.1 - Discovery

Discover Local Device Command

2.2.2 - Query

Query Local Device States Command

2.2.3 - Control

Control Local Device Command

2.2.4 - Documents & Tools

iZone API Document v2

iZone Local API Test Example

iZone API Document v1

2.3 - Cloud integration

Developer Account

2.3.1 - Authorization

Get authorization code

Get access token

Use Access Token

2.3.2 - Discovery

Discover Device Command

2.3.3 - Query

Query Device States Command

2.3.4 - Control

Control Device Command

2.3.5 - Event Report

Event Report API

2.3.6 - Result

Result Messages

3 - Examples

Control4

Home Assistant

4 - Reference

4.1 - AC Unit

Local Entry Point

Local Query Request Format

Datagram

Systemsettings

Control Actions

AC Unit On/Off

Change AC Unit Mode

Change AC Unit Fanspeed

Set AC Unit Setpoint

Change iSave On/Off

Set Sleep Timer

Types

SysOn_e

SysMode_e

SysFan_e

4.2 - Zone

Datagram

Zone

Control Actions

Change Zone Mode

Set Zone Setpoint

Set Zone Max Airflow

Set Zone Min Airflow

Set Zone Name

Types

ZoneMode_e

ZoneType_e

4.3 - Schedule

Datagram

Schedule

Control Actions

Change Schedule AC Mode

Change Schedule AC Fan

Set Schedule Name

Set Schedule Zone Settings

Set Schedule Time

Change Schedule Enable

Start Schedule Manually

4.4 - Irrigation

Local Entry Point