gs2k hostless homekit adk application note · gs2k hostless homekit adk application note...

GS2K Hostless HomeKit ADK Application Note

80560NT11581A Rev. 1.3 – 2017-12-28


80560NT11581A Rev. 1.3 of 46 2017-12-28

NOTICE

COPYRIGHTS

COMPUTER SOFTWARE COPYRIGHTS

SPECIFICATIONS ARE SUBJECT TO CHANGE WITHOUT NOTICE

While reasonable efforts have been made to assure the accuracy of this document, Telit assumes no liability resulting from any inaccuracies or omissions in this document, or from use of the information obtained herein. The information in this document has been carefully checked and is believed to be reliable. However, no responsibility is assumed for inaccuracies or omissions. Telit reserves the right to make changes to any products described herein and reserves the right to revise this document and to make changes from time to time in content hereof with no obligation to notify any person of revisions or changes. Telit does not assume any liability arising out of the application or use of any product, software, or circuit described herein; neither does it convey license under its patent rights or the rights of others.

It is possible that this publication may contain references to, or information about Telit products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that Telit intends to announce such Telit products, programming, or services in your country.

This instruction manual and the Telit products described in this instruction manual may be, include or describe copyrighted Telit material, such as computer programs stored in semiconductor memories or other media. Laws in the Italy and other countries preserve for Telit and its licensors certain exclusive rights for copyrighted material, including the exclusive right to copy, reproduce in any form, distribute and make derivative works of the copyrighted material. Accordingly, any copyrighted material of Telit and its licensors contained herein or in the Telit products described in this instruction manual may not be copied, reproduced, distributed, merged or modified in any manner without the express written permission of Telit. Furthermore, the purchase of Telit products shall not be deemed to grant either directly or by implication, estoppel, or otherwise, any license under the copyrights, patents or patent applications of Telit, as arises by operation of law in the sale of a product.

The Telit and 3rd Party supplied Software (SW) products described in this instruction manual may include copyrighted Telit and other 3rd Party supplied computer programs stored in semiconductor memories or other media. Laws in the Italy and other countries preserve for Telit and other 3rd Party supplied SW certain exclusive rights for copyrighted computer programs, including the exclusive right to copy or reproduce in any form the copyrighted computer program. Accordingly, any copyrighted Telit or other 3rd Party supplied SW computer programs contained in the Telit products described in this instruction manual may not be copied (reverse engineered) or reproduced in any manner without the express written permission of Telit or the 3rd Party SW supplier. Furthermore, the purchase of Telit products shall not be deemed to grant either directly or by implication, estoppel, or otherwise, any license under the copyrights, patents or patent applications of Telit or other 3rd Party supplied SW, except for the normal non-exclusive, royalty free license to use that arises by operation of law in the sale of a product.


80560NT11581A Rev. 1.3 of 46 2017-12-28

USAGE AND DISCLOSURE RESTRICTIONS

I. License Agreements

II. Copyrighted Materials

III. High Risk Materials

IV. Trademarks

V. Third Party Rights

The software described in this document is the property of Telit and its licensors. It is furnished by express license agreement only and may be used only in accordance with the terms of such an agreement.

Software and documentation are copyrighted materials. Making unauthorized copies is prohibited by law. No part of the software or documentation may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, without prior written permission of Telit

Components, units, or third-party products used in the product described herein are NOT fault-tolerant and are NOT designed, manufactured, or intended for use as on-line control equipment in the following hazardous environments requiring fail-safe controls: the operation of Nuclear Facilities, Aircraft Navigation or Aircraft Communication Systems, Air Traffic Control, Life Support, or Weapons Systems (High Risk Activities"). Telit and its supplier(s) specifically disclaim any expressed or implied warranty of fitness for such High Risk Activities.

TELIT and the Stylized T Logo are registered in Trademark Office. All other product or service names are the property of their respective owners.

The software may include Third Party Right software. In this case, you agree to comply with all terms and conditions imposed on you in respect of such separate software. In addition to Third Party Terms, the disclaimer of warranty and limitation of liability provisions in this License shall apply to the Third Party Right software.

TELIT HEREBY DISCLAIMS ANY AND ALL WARRANTIES EXPRESS OR IMPLIED FROM ANY THIRD PARTIES REGARDING ANY SEPARATE FILES, ANY THIRD PARTY MATERIALS INCLUDED IN THE SOFTWARE, ANY THIRD PARTY MATERIALS FROM WHICH THE SOFTWARE IS DERIVED (COLLECTIVELY “OTHER CODE”), AND THE USE OF ANY OR ALL THE OTHER CODE IN CONNECTION WITH THE SOFTWARE, INCLUDING (WITHOUT LIMITATION) ANY WARRANTIES OF SATISFACTORY QUALITY OR FITNESS FOR A PARTICULAR PURPOSE.

NO THIRD PARTY LICENSORS OF OTHER CODE SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND WHETHER MADE UNDER CONTRACT, TORT OR OTHER LEGAL THEORY, ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE OTHER CODE OR THE EXERCISE OF ANY RIGHTS GRANTED UNDER EITHER OR BOTH THIS LICENSE AND THE LEGAL TERMS APPLICABLE TO ANY SEPARATE FILES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.


80560NT11581A Rev. 1.3 of 46 2017-12-28

APPLICABILITY TABLE

Note: The features described in the present document are provided by the products equipped with the software versions equal or higher than the versions shown in the table. See also the Revision History chapter.

PRODUCT

GS2K based Modules

SW Version

5.3 x onwards


80560NT11581A Rev. 1.3 of 46 2017-12-28

Revision History

Version Date Remarks

1.0 June, 2016 Initial Release

1.1 March, 2016 Rephrased the TASK section

1.2 May, 2017 Updated Chapter 6. Native Application and Execution Sequence

1.3 Dec, 2017 Update code snippets in the following sections

5.3 HomeKit Initialization and Execution

5.4.1 Defining Accessory


80560NT11581A Rev. 1.3 of 46 2017-12-28

Table of Contents

NOTICE……… .......................................................................................................................... 2

COPYRIGHTS.. ......................................................................................................................... 2

COMPUTER SOFTWARE COPYRIGHTS ................................................................................ 2

USAGE AND DISCLOSURE RESTRICTIONS ......................................................................... 3

APPLICABILITY TABLE .......................................................................................................... 4

CHAPTER 1. INTRODUCTION ............................................................................................... 9

1.1 SCOPE .......................................................................................................................... 9 1.2 OVERVIEW..................................................................................................................... 9 1.3 TERMINOLOGY ............................................................................................................. 10 1.4 STANDARDS AND CONCEPTS ........................................................................................ 11

CHAPTER 2. FEATURES AND CAPABILITIES ................................................................... 12

CHAPTER 3. THEORY OF OPERATION ............................................................................. 13

CHAPTER 4. ARCHITECTURE ............................................................................................ 15

4.1 COMPONENTS ............................................................................................................. 16 4.1.1 Hardware ......................................................................................................... 16 4.1.2 Software .......................................................................................................... 18

4.2 TASK ........................................................................................................................... 18 CHAPTER 5. EMBEDDED APPLICATION EXECUTION SEQUENCE ................................ 20

5.1 MODULE INITIALIZATION ............................................................................................... 20 5.2 L2 AND L3 CONNECTION .............................................................................................. 21 5.3 HOMEKIT INITIALIZATION AND EXECUTION ..................................................................... 22 5.4 INTERFACE PROFILE ..................................................................................................... 26

5.4.1 Defining Accessory .......................................................................................... 26 5.4.2 Handling Accessory Control Request .............................................................. 33

CHAPTER 6. NATIVE APPLICATION AND EXECUTION SEQUENCE............................... 34

APPENDIX A ADD NEW SERVICES AND CHARACTERISTICS ........................................ 42

A.1 ADDING NEW SERVICES ............................................................................................... 42 A.2 ADDING NEW CHARACTERISTICS .................................................................................. 42


80560NT11581A Rev. 1.3 of 46 2017-12-28

List of Figures Figure 1: HTTP module on Home Automation ......................................................................... 13

Figure 2: Test Setup with EVB Running as AP ........................................................................ 15

Figure 3: Test Setup with EVB Running in Station Mode ........................................................ 15

Figure 4: GS2200M SKB ......................................................................................................... 16

Figure 5: GS2101M EVB ......................................................................................................... 17

Figure 6: Threads in HomeKit ADK ......................................................................................... 18

Figure 7: L2-L3 Connection ..................................................................................................... 21

Figure 8: Communication between Nodes............................................................................... 22

Figure 9: I2C Communication Between GS Node & Apple WAC Chip .................................... 23

Figure 10: Connecting to an AP .............................................................................................. 34

Figure 11: Add Accessory ....................................................................................................... 35

Figure 12: Accessory Select .................................................................................................... 36

Figure 13: Entry of Passcode .................................................................................................. 37

Figure 14: Initiation of Pairing .................................................................................................. 38

Figure 15: Successful Pairing .................................................................................................. 39

Figure 16: Light Sensor Reading ............................................................................................. 40

Figure 17: Accessory Setup Prints .......................................................................................... 41


80560NT11581A Rev. 1.3 of 46 2017-12-28

List of Tables Table 1: Glossary of Terms ..................................................................................................... 10

Table 2: Hardware Components of GS2200M SKB ................................................................ 16

Table 3: Hardware Components of GS2101M ......................................................................... 17

Table 4: Software Components ............................................................................................... 18

Table 5: APIs by HomeKit Module ........................................................................................... 20

Table 6: List of Commands ...................................................................................................... 43


80560NT11581A Rev. 1.3 of 46 2017-12-28

Introduction

1.1 SCOPE

This document provides an overview about the GainSpan GS2000® based HomeKit Application Development Kit (ADK) and describes the software and hardware architecture, network topology, functional features, API’s, Application Execution Sequence of the Embedded and Mobile application (if applicable). HomeKit ADK provides user interface for its accessory to build user application on it.

This document assumes that the reader is generally familiar with GainSpan SoC products, Internet Protocol (IP) networks, and the operation of 802.11 wireless devices.

1.2 OVERVIEW

GainSpan HomeKit ADK is a development platform based on Apple’s HomeKit framework, which can be used to develop/implement any custom applications by integrating different HomeKit accessories.

NOTE: GainSpan SDK is mandatory for any development on HomeKit ADK.


80560NT11581A Rev. 1.3 of 46 2017-12-28

1.3 TERMINOLOGY

Below table lists the different terminologies used in this document.

Table 1: Glossary of Terms

Term Explanation

AP Access Point

API Application Program Interface

ADC Analog-to-Digital converter

JSON Java Script Object Notation

UART Universal Asynchronous Receiver/Transmitter

HTTP Hypertext Transfer Protocol

DNS Domain Name System

mDNS multicast Domain Name System

DNS-SD DNS Service Discovery

Device An Apple iPod, iPhone or iPad (typically running iOS, Apple’s mobile operating system)

Accessory Any product intended to interface with a device via the means described in HomeKit specification.

Product Either a MAC or an afore mentioned device

HAP HomeKit Accessory Protocol

SRP Secure Remote Password protocol


80560NT11581A Rev. 1.3 of 46 2017-12-28

1.4 STANDARDS AND CONCEPTS

Standards

Generic

• HTTP

• MDNS/DNS-SD

Specific

• JSON parsing

Concepts

• Apple HomeKit Framework


80560NT11581A Rev. 1.3 of 46 2017-12-28

Features and Capabilities

This section provides the features and capabilities of GainSpan HomeKit ADK:

Features

1. Supports all HomeKit services defined in the Apple HomeKit Accessory Protocol Specification Release 7 (R7)

2. Limited AP and Station mode

3. Provisioning

4. OTAFU

Capabilities

• JTAG for debugging on GS2200M SKB/ GS2101M EVB


80560NT11581A Rev. 1.3 of 46 2017-12-28

Theory of Operation

HomeKit ADK demonstrates how an iOS device communicates with an accessory using HomeKit Accessory Protocol (HAP). For example, as iOS device uses HAP to discover, explore and interact with HomeKit accessories via Wi-Fi. Here, the temperature and light sensors on GS EVB/SKB are referred to as accessories. Apple HomeKit specification is implemented on top of HTTP layer as shown in the below figure.

This defines two basic roles or device types:

a. Accessory (HAP Accessory Server): - The device to which the sensor or the actuator is connected i.e., GS2000 with sensors or actuator connected to it.

b. Controller (HAP Client): - The device that gets data from the accessory to display/control the accessory that is an iPhone/any Apple handheld device/cloud server.

Figure 1: HTTP module on Home Automation

Following are different steps involved in this demo

• Discovery using Bonjour

• Session security using HomeKit Accessory Protocol Pairing

• Describing accessories in JSON

• Communications between Controllers and accessories over HTTP

Discovery

HomeKit ADK uses Bonjour services for advertising available accessories where the Controller finds it and initiates pairing.


80560NT11581A Rev. 1.3 of 46 2017-12-28

Pairing

Paring is the procedure where an accessory and controller bind with each other. During this a per-session shared key is also exchanged between Controller and Accessory. (One can compare this with WPS-PIN procedure, where the AP credential is given to the client).

Once a controller is paired with the accessory, the controller can discover all the HomeKit profiles and services supported by accessory and get information to control them. All the data transfer is encrypted with the temporary key generated for each session. The process to generate the temporary key is called verification. The verification process happens before the profile information discovery or reading or writing of profile parameters. For each session, the controller initiates the verification procedure.

Profile

HomeKit profile defines few services and defines how to read/write different parameters of these services.

A service denotes a physical sensor or actuator. There can be multiple types of services based on the sensor or actuator, for example, light bulb, Garage door and so on. An accessory might support multiple services of same kind and different kind; meaning an accessory may support three light bulb services and a garage door service.

Each service has multiple characteristics. A characteristic denotes a particular feature of the service, for example, in a light bulb, ON-OFF, controlling brightness or Hue level are the characteristics. There can be few mandatory characteristics for a service (ON-OFF for light bulb) and few optional based on the sensor actuator capability (brightness control, Hue level etc.)

Each service and characteristics are identified by predefined type (UUID given by HomeKit Profile). User also gives a unique identification number “iid” to each service and characteristic. A physical device can support multiple accessories having multiple services (for example, Bridge that aggregate all the information of different sensor/actuator information using any other protocol). Each accessory is also defined by a unique ID called “aid”.

To read/write to the parameters, the controller uses “aid” and “iid” combination. Controller can send multiple read or write request in one request, but all should be of same type i.e. all should be either read or write.

Controller can enable/disable event notification. If event notification is enabled for a characteristic, then the controller should be indicated/notified any manual changes happening on the characteristic, for example, light bulb is switched ON/OFF manually.


80560NT11581A Rev. 1.3 of 46 2017-12-28

Architecture

The HomeKit ADK consists of GS node working in two modes:

• Limited AP mode

• Client mode

Limited AP Mode

Figure 2: Test Setup with EVB Running as AP

In AP mode, the HomeKit device/controller, is associated to GS LAP.

NOTE:

• IPv6 is not supported when the EVB is configured as an AP.

• Both IPv4 and IPv6 modes are supported when the EVB is

configured as a Station

Client Mode

Figure 3: Test Setup with EVB Running in Station Mode

Figure 2 shows the EVB (STA) associated to an AP to which the HomeKit device/controller is also associated. UART console connected to GS EVB monitors debug messages and is used to send configuration commands for compliance testing.


80560NT11581A Rev. 1.3 of 46 2017-12-28

4.1 COMPONENTS

HomeKit ADK consists of the following hardware and software components.

4.1.1 Hardware HomeKit ADK comes with following hardware components for GS2200M SKB and GS2101M EVB:

Table 2: Hardware Components of GS2200M SKB

Component Description

GS2200M SKB GS2200M module transmits sensor data over Wi-Fi.

LEDs Indicates Power On, Operation mode (Limited AP or Client) and ACTIVE or SLEEP Program mode

TMP102 Temperature sensor on GS2200 SKB

MAX44009 Light sensor on GS2200 SKB

Apple WAC IC U6 Apple authentication IC

Figure 4: GS2200M SKB


80560NT11581A Rev. 1.3 of 46 2017-12-28

Table 3: Hardware Components of GS2101M


GS2101M EVB GS2101M module transmits sensor data over Wi-Fi.

LEDs Indicates Power On, Operation mode (Limited AP or Client) and Run or Program mode

Apple WAC IC U24 Apple authentication IC

Figure 5: GS2101M EVB

GS2101MIP Wi-Fi Module AppleWAC IC (U24)

Main Power ON/OFF Switch

PROGRAM/RUN Switch and J22 Jumper Header

Mini USB Cable to USB0


80560NT11581A Rev. 1.3 of 46 2017-12-28

4.1.2 Software GainSpan HomeKit ADK uses the following software components.

Table 4: Software Components


Embedded Firmware Application An embedded application that runs on the GainSpan EVB/SKB board which is the source of the Temp and Light sensor and runs the HTTP server.

Native application on iOS or MAC HomeKit application.

HomeKit test application HomeKit test application to demonstrates various capabilities and features.

4.2 TASK

Following figure shows different threads which gets executed in HomeKit ADK.

Figure 6: Threads in HomeKit ADK

HomeKit Application Threads are as listed below:

Main: Thread priority of the main thread is 15. It is created by AppMainCtx_Init().

AppMainCtx_Init that is invoked after boot rom code is executed. Following are

responsibilities of the main thread.


80560NT11581A Rev. 1.3 of 46 2017-12-28

o Handles System/Network events AppSm_MsgProcess:courier

o Initializes clock control/Wif message system/software timer/file system/wdd/network stack/WPA Supplicant.

o Sends Boot request to the WLAN for initialization.

Web Server: Thread Priority of the webserver is 16.

HTTPd server thread listens for incoming connections and handles the http client requests.

UART Read: Thread Priority of UartRead thread is 18.

Waits for user COMMANDS to run any available DEMOS. Following are the responsibilities of the thread that reads UART.

a) Reads the UART for commands and runs the appropriate demos and configures the parameters as given.

b) Generates and prints the setup code/home kit accessory passcode

c) Prepares the GS module to DeepSleep state by configuring UART_RX as GPIO interrupt source for wakeup

On Power Up, HomeKit ADK starts MAIN Task AppMainCtx_ThreadEntry(), which performs

all required GainSpan Module initializations, starts App_UartThreadEntry() Thread and

NCM.

Once the L2 connection is established successfully, network service initializations are triggered where mDNS module is initialized and http server is started. After network services are up, HomeKit initialization is started. HomeKit initialization will perform HAP Profile initialization, registers callback which handles all the respective events as when received from HAP Controller.


80560NT11581A Rev. 1.3 of 46 2017-12-28

Embedded Application Execution Sequence

This section describes the embedded application execution sequence of HomeKit Application in detail.

5.1 MODULE INITIALIZATION

GS HomeKit application does all the basic system initializations and calls App_UartThreadEntry() which creates the “appUartThread”. This thread takes input from

serial interface to choose the demo to be run. Once the user chooses the demo, HomeKit initialization process starts.

Reference

AppMainCtx_ThreadEntry();

(

System initializations ---

AppHomeKit_RegisterTestHarnessDemo(); // Default registered test Demo.

AppInit_WddMsgHdlrInit(pAppCtx); //Initialise Wdd Message Handler.

App_NwStackInit(pAppCtx); //Initialize Nw statck. This is a onetime

initialization.

GsnHeIf_DriverDeinit(); // De-initializing the hardware encryption engine

App_WpaSupplicantInit(pAppCtx); // Initialise WPA Suppliacnt

App_RandomNumGenInit(); // Generate random number and its seed

App_Start(pAppCtx); // Start the interface

App_UartReadThreadInit(); // Initialize UART thread for communicating for

exchanging command/response over UART1 interface

//Handle events forever

}

The following table describes the APIs provided by the HomeKit module:

Table 5: APIs by HomeKit Module

Name Input Parameters

Output Parameters

Description

GsnHomeKit_Init App Context Status This function initializes HomeKit module. This API will register the HomeKit service with mDNS and be prepared to take paring request from HomeKit controller. This API will initialize and restore the previous state based on the content in the HomeKit persistent memory.

GsnHomeKit_EventNotify Response structure

This function is called by the user to notify event to the controller e.g. when a light bulb is turned ON or OFF manually. This information is sent to all the connected controllers.


80560NT11581A Rev. 1.3 of 46 2017-12-28

5.2 L2 AND L3 CONNECTION

Figure 7: L2-L3 Connection

Once event for L2 connection is successful, it completes the L3 connection as shown in the above figure, starts network services, and starts HomeKit initialization.


80560NT11581A Rev. 1.3 of 46 2017-12-28

5.3 HOMEKIT INITIALIZATION AND EXECUTION

Figure 8: Communication between Nodes

HomeKit API is invoked to start HomeKit service. This API would register HomeKit service with Bonjour and registers for few URIs with HTTP. So, the prerequisite to call this API is to start both Bonjour (mDNS) and HTTP services. Once the API is called, the HomeKit service is established and the available services are advertised (broadcasted) using Bonjour. Controller discovers these services and initiates Paring. All the pairing and verification procedure is performed internally without user intervention. But it can be monitored using registered callbacks which indicate various events happening during paring and verification process.

NOTE: HomeKit user would enable/disable standby during paring or verification process. User can decide if the HomeKit module is in middle of paring/verification based on the event indicated using the registered callbacks.

HomeKit would use WAC APIs to read the MFi certificate from the Apple chip.

Pairing and Verification procedure while adding an Accessory to the Controller:

Pairing

In pairing process, the controller sends a pairing request over HTTP to the GS Node, which in turns requests the key from the WAC IC. When the WAC IC responds with the Key response, it is matched with the key received from controller to authenticate. Then GS Node sends the pairing response using HTTP post.

Once the device is paired, the session is closed.


80560NT11581A Rev. 1.3 of 46 2017-12-28

Verification

Once pairing is successful, GS Node maintains the Controller ID in its list of paired controllers. The shared key is stored on every successive verification request while reopening a session.

Here a temporary key is generated to verify the verification request. If the session is not closed then verification process is skipped with a response to it and subsequent pairing is done directly.

Controller (iMAC or any iOS device) and GainSpan module communicate via Wi- Fi. And GS module and Apple WAC Chip communicate via I2C interface. The pin connections for the same are shown below.

Figure 9: I2C Communication Between GS Node & Apple WAC Chip

Reference Code

After successfully establishing L3 connections “App_NetworkServicesStart()”, will

be called from the “AppSm_ConnectSuccessProcess()”. This is the part of NCM

connection establishment procedure.

App_sm.c

PRIVATE VOID AppSm_ConnectSuccessProcess(APP_MAIN_CTX_T *pAppCtx)

{

*

*

*

/*In both AP and client case, start the web server*/

App_NetworkServicesStart(pAppCtx);

}

App_network_services.c

PUBLIC UINT32 App_NetworkServicesStart(APP_MAIN_CTX_T *pAppCtx)

{

*

*

#ifdef APP_MDNS_ENABLE

AppDbg_Printf("Starting MDNS...\r\n");

App_MdnsInit(pAppCtx);

#endif


80560NT11581A Rev. 1.3 of 46 2017-12-28

*

App_StartWAC(pAppCtx)

{

/* Start HTTP Server */

AppDbg_Printf("Starting HTTPD...\r\n");

App_HttpdStart(pAppCtx);

}

*

*

#ifdef ADK_HOMEKIT_ENABLE

if( 0 == pAppRtcLtchInfo->wacEnableFlag )

{

AppDbg_Printf("Starting HomeKit...\r\n");

AppHomeKit_Init( pAppCtx );

AppDbg_Printf("HomeKit successfully started :)\r\n");

}

#endif

}

Initialization of HomeKit will be done by “AppHomeKit_Init()”

GSN_STATUS AppHomeKit_Init( APP_MAIN_CTX_T *pAppCtx )

{

UINT8 category = AppHomeKit_GetCategory();

AppHomeKit_ProfileInit();

AppDbg_Printf("\r\nAuthentication Passcode (xxx-xx-xxx) = %s\r\n",

pAppCtx->config.hkCfg.authPwd );

/**< Setup code is modified, so store the setup code configuration.

*/

if( pAppCtx->config.hkCfg.modified == 1 )

AppConfig_Save( &pAppCtx->config );

pAppCtx->config.hkCfg.configNum = hkConfigId;

pAppCtx->config.hkCfg.accessoryCatagory = category;

return GsnHomeKit_Init(pAppCtx,&pAppCtx->if0.mdns,

&pAppCtx->config.hkCfg, AppHomeKit_EventCb );

UINT8 *certAddress = NULL;

UINT16 certLength = 0;

/* if iCloud Certification Validation is enabled then add CA cert

information */

if(pAppCtx->config.hkCfg.iCloudPersistMem.iCloudCAValEnable == 1)

{

/* Load Certs from filesystem */

App_SslCertificateLoad(pAppCtx, &certAddress, &certLength);

}

status=GsnHomekit_iCloudInit(&pAppCtx->if0.nwifCtx,certAddress,

certLength);


80560NT11581A Rev. 1.3 of 46 2017-12-28

if((status==GSN_SUCCESS)&&

(pAppCtx->config.hkCfg.iCloudPersistMem.iCloudEnableFlag))

{

AppDbg_Printf("\r\niCloud Service Info enabled:%d, state:%d

\r\n",pAppCtx->config.hkCfg.iCloudPersistMem.iCloudServiceEnabled,

pAppCtx->config.hkCfg.iCloudPersistMem.iCloudServiceState);

}

}

Initialize the Accessory Category for the Accessory. These categories are defined in “gsn_homekit.h”.

#define GSN_HK_ACCESSORY_CATAGORY_OTHER 1

#define GSN_HK_ACCESSORY_CATAGORY_BRIDE 2

#define GSN_HK_ACCESSORY_CATAGORY_FAN 3

#define GSN_HK_ACCESSORY_CATAGORY_GARAGE 4

#define GSN_HK_ACCESSORY_CATAGORY_LIGHTBULB 5

#define GSN_HK_ACCESSORY_CATAGORY_DOORLOCK 6

#define GSN_HK_ACCESSORY_CATAGORY_OUTLET 7

#define GSN_HK_ACCESSORY_CATAGORY_SWITCH 8

#define GSN_HK_ACCESSORY_CATAGORY_THERMOSTAT 9

#define GSN_HK_ACCESSORY_CATAGORY_SENSOR 10

#define GSN_HK_ACCESSORY_CATAGORY_SECURITY_SYSTEM 11

#define GSN_HK_ACCESSORY_CATAGORY_DOOR 12

#define GSN_HK_ACCESSORY_CATAGORY_WINDOW 13

#define GSN_HK_ACCESSORY_CATAGORY_WINDOW_COVERING 14

#define GSN_HK_ACCESSORY_CATAGORY_PROGRAMMABLE_SWITCH 15

Initialize the HomeKit Profile using “AppHomeKit_ProfileInit()”. This will initialize the Accessory list data structures.

void AppHomeKit_ProfileInit(void)

{

if( pCurrentDemo->accessoryInit )

pCurrentDemo->accessoryInit();

}

“accessoryInit” is a function pointer which is initialized by respective Accessory Initialization Function.


80560NT11581A Rev. 1.3 of 46 2017-12-28

5.4 INTERFACE PROFILE

5.4.1 Defining Accessory Following steps need to be performed to define accessories,

Memory needs to be defined for the following:

o Define the accessory list and add all the accessories which are supported by the device

o Define the accessory by adding all the services, accessory supports.

o Define the services by adding the list of characteristics each service supports.

o Define characteristics for each service.

Initialization must be done for the above defined memory as follows:

o Initialize all the characteristics using the initialization MACRO for each characteristic.

o Add the characteristics to corresponding services.

o Add services to the corresponding accessories.

o Add all accessories to accessories list.

Example

In the above code snippet, all the characteristics, service, service list, accessory and accessories list are defined.


80560NT11581A Rev. 1.3 of 46 2017-12-28

The above code snippet shows how the characteristics, services, accessory are initialized. A single HomeKit embedded product can support one or more accessories. So, the information about the accessories will be stored in the data structure “GSN_HK_ACCESSORY_LIST_T”.

typedef struct GSN_HK_ACCESSORY_LIST

{

UINT8 numOfAccessory;

GSN_HK_ACCESSORY_INFO_T **pAaccList;

}GSN_HK_ACCESSORY_LIST_T;

ACCESSORY INFO

Each Accessory must have two or more services. This information will be stored using the structure “GSN_HK_ACCESSORY_INFO_T”. Each Accessory will be identified by Unique Identification Number called Accessory Identification represented with “aid”.

typedef struct GSN_HK_SERVICE_INFO

{

UINT8 numOfChar;

/**< Instance Id. Though the number should have range from 1 to

18446744073709551616, we define it as UINT16, as in embedded system

like

ours, we dont foresee to support for such a big instance Id. */

UINT8 iid;

const UINT8* type;

UINT8 hidden;

UINT8 primary;

UINT8 *pLinked;

GSN_HK_CHARACTERISTICS_INFO_T **pCharList;


80560NT11581A Rev. 1.3 of 46 2017-12-28

}GSN_HK_SERVICE_INFO_T;

Out of which first service is called Accessory Information service which gives Characteristics information about Accessory (Accessory Identity, Manufacturer, Model, Name, and Serial Number).

Second service can be any other services defined by Apple Home kit. Examples of different services are Light Sensor, Switch, Garage Door Opener, Thermostat and so on.

SERVICE INFO

The data structure used for maintaining the services is “GSN_HK_SERVICE_INFO_T”. This structure contains information about Characteristics (For example, Number of Characteristics of the service, and list of Characteristics etc.). Each Service will be identified by Unique Instance Identification number represented with “iid”.

typedef struct GSN_HK_SERVICE_INFO

{

UINT8 numOfChar;

/**< Instance Id. Though the number should have range from 1 to

18446744073709551616, we define it as UINT16, as the embedded system

does not support large size instance Id. */

UINT16 iid;

const UINT8* type;

GSN_HK_CHARACTERISTICS_INFO_T **pCharList;

}GSN_HK_SERVICE_INFO_T;

CHARACTERISTICS INFO

The data structure used for maintaining the services is “GSN_HK_CHARACTERISTICS_INFO_T”. This structure contains information about format, UUID defined by the HomeKit specification, value of the characteristics, minimum and maximum value, and increment or decrement steps level (For example temperature increase by 1 step/ decrease by 1 step). Just like service each characteristic will be identified by Unique Instance Identification number represented with “iid”.

typedef struct GSN_HK_CHARACTERISTICS_INFO

{

/**< iid given by the user */

UINT8 iid;

/**< data type used */

UINT8 format;

/*flag specifies what permissions it supports like Read, Write, event

and what all Meta data it supports like unit, min,

max, min steps*/

UINT8 flag;

/**< 1 if event notification is enabled. */

UINT8 eventNotif;

/**< UUID defined by the HomeKit specification */

const UINT8* type;

GSN_HK_DATA_TYPE_T value;

GSN_HK_DATA_TYPE_T max;


80560NT11581A Rev. 1.3 of 46 2017-12-28

GSN_HK_DATA_TYPE_T min;

GSN_HK_DATA_TYPE_T step;

const UINT8* pUnit;

}GSN_HK_CHARACTERISTICS_INFO_T;

Code Initialization

HomeKit initialization is shown below by referring to temperature sensor example.

Step 1: Defining Accessory

a. User has to define the accessories list and add all the accessories it supports.

GSN_HK_ACCESSORY_LIST_T AccessoryListInfo;

GSN_HK_ACCESSORY_INFO_T *AccessoriesList [] = {&

LightSensorAccessory};

b. User has to define accessory by adding all the services it supports.

i. Accessory Info

GSN_HK_ACCESSORY_INFO_T LightSensorAccessory;

ii. Service Info List

GSN_HK_SERVICE_INFO_T *ServiceList[] = {&AccessoryInfoService,

&LightSensorService};

c. User has to define the services adding the list of characteristics it supports.

i. Service Info

GSN_HK_SERVICE_INFO_T AccessoryInfoService;

GSN_HK_SERVICE_INFO_T LightSensorService;

d. User has to define characteristics for each service it supports.

i. Characteristic of AccessoryInfoService:

GSN_HK_CHARACTERISTICS_INFO_T PAI;

GSN_HK_CHARACTERISTICS_INFO_T PAMU;

GSN_HK_CHARACTERISTICS_INFO_T PAMD;

GSN_HK_CHARACTERISTICS_INFO_T PAN;

GSN_HK_CHARACTERISTICS_INFO_T PAS;

GSN_HK_CHARACTERISTICS_INFO_T *AccessoryInfoCharList[] = {&PAI,

&PAMU, &PAMD, &PAN, &PAS };

ii. Characteristic of LightSensorService:

GSN_HK_CHARACTERISTICS_INFO_T PLTSCALL;

GSN_HK_CHARACTERISTICS_INFO_T PLTSN;

GSN_HK_CHARACTERISTICS_INFO_T PLTSSA;

GSN_HK_CHARACTERISTICS_INFO_T PLTSSF;

GSN_HK_CHARACTERISTICS_INFO_T PLTSST;

GSN_HK_CHARACTERISTICS_INFO_T PLTSSLB;


80560NT11581A Rev. 1.3 of 46 2017-12-28

GSN_HK_CHARACTERISTICS_INFO_T *LightSensorCharList [] = {&PLTSCALL,

&PLTSN, &PLTSSA, &PLTSSF, &PLTSST, &PLTSSLB};

Step 2: Initializing Accessory related data structures.

Initialize the Characteristic Of AccessoryInfoService:

AccessoryInfoService.numOfChar = 5 (Refer *AccessoryInfoCharList [] )

AccessoryInfoService.iid = 1;

AccessoryInfoService.type = GSN_HK_SERVICE_TYPE_INFO; (Refer

gsn_homekit_profile.h for MACRO)

AccessoryInfoService.pCharList = AccessoryInfoCharList;

/**< Initialize the characteristics of Accessory Information

Refer APP_HK_CMD_TBL for expansion of Characteristic names*/

GSN_HK_PROFILE_CHAR_IDENTITY_INIT ( PAI, 2, 0 );

GSN_HK_PROFILE_CHAR_MANUFACTURER_INIT ( PAMU, 3, "GainSpan");

GSN_HK_PROFILE_CHAR_MODEL_INIT ( PAMD, 4, "GS2011M");

GSN_HK_PROFILE_CHAR_NAME_INIT ( PAN, 6, "HK-GS2000" );

GSN_HK_PROFILE_CHAR_SERIAL_NUM_INIT ( PAS, 7, "5.2.0");

Initialize the Characteristic Of LightSensorService:

LightSensorService.numOfChar = 6 (Refer *LightSensorCharList[])

LightSensorService.iid = 8; (Increment of iid by 1 )

LightSensorService.type = GSN_HK_SERVICE_TYPE_LIGHT_SENSOR; (Refer

gsn_homekit_profile.h for MACRO)

LightSensorService.pCharList = LightSensorCharList;

GSN_HK_PROFILE_CHAR_CUR_AMBNT_LT_LVL_INIT ( PLTSCALL, 9, 10 );

GSN_HK_PROFILE_CHAR_NAME_INIT ( PLTSN, 10, "GS-LIGHT-SEN");

GSN_HK_PROFILE_CHAR_ST_ACT_INIT ( PLTSSA, 11, 0 );

GSN_HK_PROFILE_CHAR_ST_FLT_INIT ( PLTSSF, 12, 0 );

GSN_HK_PROFILE_CHAR_ST_TMPRD_INIT ( PLTSST, 13, 0 );

GSN_HK_PROFILE_CHAR_ST_LOW_BAT_INIT ( PLTSSLB, 14, 0 );

Initialize the Accessory

LightSensorAccessory.numOfServices = 2(AccessoryInfoService and

LightSensorService)

LightSensorAccessory.aid = 1;

LightSensorAccessory.pServiceList = ServiceList (Refer b.2 in STEP1);

Initialize the Accessory List

AccessoryListInfo.numOfAccessory = 1;

AccessoryListInfo.pAaccList = AccessoriesList;

Step 3: Initialize the Application level Home Kit Configuration

There are 2 important data structures for Application level HomeKit configuration.

1. GSN_HOMEKIT_PERSISTENT_MEM


80560NT11581A Rev. 1.3 of 46 2017-12-28

2. GSN_HOMEKIT_CTRL_T

typedef struct GSN_HOMEKIT_PERSISTENT_MEM

{

UINT8 modified; /**< set to true if homekit modifies it */

UINT8 scope; /**< One of the value from GSN_MDNS_SCOPE_T */

UINT8 accessoryCatagory; /**< Accessoru catagory */

UINT32 configNum; /**< Configuration sequence number */

UINT8 authPwd[ 12 ]; /**< 10 ( XXX-XX-XXX) + the string end + one

extra */

UINT8 DevId[20]; /**< stores string formed from MAC address */

UINT8 modelName[32]; /**< stores string to be used in mDNS for model

name */

UINT8 DevDiscoveryId[32]; /**< stores string to be used in mDNS

device ID */

UINT32 pubKey[32 >> 2 ]; /**< Accessory public key */

UINT32 privKey[32 >> 2]; /**< Accessory private key */

GSN_HOMEKIT_CTRL_T CtrlList[16]; /**< Stores info on paired

controller */

GSN_ICLOUD_PERSISTENT_MEM_T iCloudPersistMem;

UINT8 R8_support_enable;

}GSN_HOMEKIT_PERSISTENT_MEM_T;

typedef struct GSN_HOMEKIT_CTRL

{

UINT32 LPTK[32 >> 2];/**< Stores the controllers temporal Public key

*/

UINT32 CtrlId[36 >> 2];/**< Stores the controllers Identification */

UINT8 permission;/**< Stores the controller administrator permission

*/

UINT8 enabled;/* set to true if local pair verification session is

present */

UINT8 iCloudCtrlIndex; /* store icloudController Index */

}GSN_HOMEKIT_CTRL_T;

In this data structure application should populate the following things. Remaining fields will be populated by HOME KIT GEPS Library.

1. Configuration Number:

This is number which get incremented by Adding new service to the Accessory, otherwise it remains same.

2. Access Category:

Based on the Accessory, there are 15 Accessory categories are defined. Following are MACRO’s defined in “gsn_homekit.h”.

#define GSN_HK_ACCESSORY_CATAGORY_OTHER 1

#define GSN_HK_ACCESSORY_CATAGORY_BRIDE 2

#define GSN_HK_ACCESSORY_CATAGORY_FAN 3

#define GSN_HK_ACCESSORY_CATAGORY_GARAGE 4

#define GSN_HK_ACCESSORY_CATAGORY_LIGHTBULB 5

#define GSN_HK_ACCESSORY_CATAGORY_DOORLOCK 6

#define GSN_HK_ACCESSORY_CATAGORY_OUTLET 7

#define GSN_HK_ACCESSORY_CATAGORY_SWITCH 8


80560NT11581A Rev. 1.3 of 46 2017-12-28

#define GSN_HK_ACCESSORY_CATAGORY_THERMOSTAT 9

#define GSN_HK_ACCESSORY_CATAGORY_SENSOR 10

#define GSN_HK_ACCESSORY_CATAGORY_SECURITY_SYSTEM 11

#define GSN_HK_ACCESSORY_CATAGORY_DOOR 12

#define GSN_HK_ACCESSORY_CATAGORY_WINDOW 13

#define GSN_HK_ACCESSORY_CATAGORY_WINDOW_COVERING 14

#define GSN_HK_ACCESSORY_CATAGORY_PROGRAMMABLE_SWITCH 15

Example

Light sensor Home Kit Accessory is the one of the example of HomeKit, required methods are defined in “app_homekit_light_sensor_service.c”.

“accessoryInit” function pointer is initialized with “AppHomeKit_AccessoryInit”. This method

does the basic initialization for AccessoryList and Accessory.

static VOID AppHomeKit_AccessoryInit( VOID )

{

AppDbg_Printf("Initialize Accessory\r\n");

Accessory.numOfServices=sizeof(ServiceList)/sizeof( VOID* );

Accessory.aid = aidCount++;

Accessory.pServiceList = ServiceList;

AccessoryListInfo.numOfAccessory=sizeof(AccessoriesList)/

sizeof(VOID*);

AccessoryListInfo.pAaccList = AccessoriesList;

AppHomeKit_ServiceInit();

}

AppHomeKit_ServiceInit() method will initialize the Accessory services List and Service

Characteristics. AppHomeKit_DefaultCharInit() is responsible for setting the default

Initialization of Services and its associated characteristics and saving them as a configuration file.

static VOID AppHomeKit_ServiceInit( VOID )

{

AppDbg_Printf("Initialize Services and characteristics\r\n");

AppDbg_Printf("Initializing 'Accessory information' Service and

its characteristics\r\n");

/*Accessory Information and Light sensor services are already

initialized as part of test harness*/

AppHomeKit_DefaultCharInit();

AppHomeKit_UpdateLightValue();

AppDbg_Printf("\r\nCurrent Light value = %f\r\n",

PLTSCALL.value.f);

/**< Start timer to take light value at periodic interval */

AppHomeKit_RegularUpdateInit(TIMER_INTERRUPT_1_S,

AppHomeKit_UpdateAndNotifyLightValue );

}


80560NT11581A Rev. 1.3 of 46 2017-12-28

5.4.2 Handling Accessory Control Request HomeKit module calls the user registered callback API to indicate the accessory controlling requests from the controller. For this purpose, the callback is called with the following events.

The callback pMsgIn contains valid pointer of type GSN_HK_RD_WR_EV_REQ_T if it is characteristics read, write or event request. User should fill the same structure in the callback. The pMsgOut is NULL in this case. HomeKit module uses this filled request structure to respond to the controller.

In case of Accessory discovery request, the pMsgIn is NULL and pMsgOut has a valid pointer. User is expected to point to accessory list. HomeKit module will take the details from the accessory list and form the response to the controller.


80560NT11581A Rev. 1.3 of 46 2017-12-28

Native Application and Execution Sequence

This section briefs about the native application execution sequence that should be followed after the accessory is configured and initialized.

For more information refer GS2K Hostless HomeKit User Guide.

Steps to be performed for the demo:

1. From any iOS device, open Wi-Fi settings and connect to the same wireless network to which SKB was connected.

Figure 10: Connecting to an AP


80560NT11581A Rev. 1.3 of 46 2017-12-28

2. Launch “HOME App" from iOS device and tap Add Accessory.

Figure 11: Add Accessory


80560NT11581A Rev. 1.3 of 46 2017-12-28

3. Select the Accessory to be added to the HomeKit.

Figure 12: Accessory Select


80560NT11581A Rev. 1.3 of 46 2017-12-28

4. Enter the pass code manually, the default authentication code 101-48-505.

Figure 13: Entry of Passcode


80560NT11581A Rev. 1.3 of 46 2017-12-28

5. HOME App pairs and authenticates the HomeKit Accessory.

Figure 14: Initiation of Pairing


80560NT11581A Rev. 1.3 of 46 2017-12-28

6. Upon successful pairing, tap Done.

Figure 15: Successful Pairing


80560NT11581A Rev. 1.3 of 46 2017-12-28

7. The light sensor value will be displayed on the HOME App. The sensor is located at one of the corners of SKB, labelled as U6. The Light sensor value can be changed using a torch or by covering the sensor and the values can be monitored in the HOME App.

Figure 16: Light Sensor Reading


80560NT11581A Rev. 1.3 of 46 2017-12-28

8. Serial Console: For Pairing and Data fetching procedure

Figure 17: Accessory Setup Prints


80560NT11581A Rev. 1.3 of 46 2017-12-28

Appendix A Add New Services and Characteristics

A.1 ADDING NEW SERVICES

Declare a Macro for the new service with its UUID value.

Example:

#define GSN_HK_SERVICE_TYPE_XXX "YY"

Here, XXX is the new service and “YY” string is the UUID value obtained from the ’UUID’ section for IP

000000YY-0000-10000-8000-0026bb765291.

A.2 ADDING NEW CHARACTERISTICS

Declare a MACRO to set the values of elements of ‘GSN_HK_CHARACTERISTICS_INFO_T’.

User has to provide the variable name of type GSN_HK_CHARACTERISTICS_INFO_T, iid and

default value.

This MACRO will fill the iid, value to this variable. It would set the rest of the elements of this variable as per the information provided for this characteristics in the Apple HomeKit specification.

The flag will be set with the value OR’ed with,

• GSN_HOMEKIT_PROF_FLAG_PERM_RD if the characteristic is readable.

• GSN_HOMEKIT_PROF_FLAG_PERM_WR if the characteristic is writable.

• GSN_HOMEKIT_PROF_FLAG_PERM_EV if event notification can be set for this characteristic.

• GSN_HOMEKIT_PROF_FLAG_MWTA_MX if maximum value is defined for this characteristic.

• GSN_HOMEKIT_PROF_FLAG_MWTA_MN if minimum value is defined for this characteristic.

• GSN_HOMEKIT_PROF_FLAG_MWTA_ST if step is defined for this characteristic.

• GSN_HOMEKIT_PROF_FLAG_MWTA_UT if unit is defined for this characteristic.

If ‘GSN_HOMEKIT_PROF_FLAG_MWTA_MX’ is set in flag then max value should also be set.

If ‘GSN_HOMEKIT_PROF_FLAG_MWTA_MN’ is set in the flag then min value also has to be set.

If ‘GSN_HOMEKIT_PROF_FLAG_MWTA_ST’ is set in the flag then step value has also to be set.

If ‘GSN_HOMEKIT_PROF_FLAG_MWTA_UT’ is set in the flag then unit pointer should also be

initialized.

By default, the ‘eventNotif’ should be set to 0. Format field should be filled with the data type it uses, like char/int/float. Update characteristics from GS Node.


80560NT11581A Rev. 1.3 of 46 2017-12-28

List of commands for changing the characteristics (like Temp, Humidity, and so on) of the thermostat.

Table 6: List of Commands

Characteristics Access Restriction

Possible values

Abbreviation Example

Current Heating cooling state

Read 0 - Off

1 – Heater on

2 – cooler on

PTCS Get:

ptcsg

ptcs = 0

OK

SET:

ptcss 1

ptcs is set to 1

OK

Target Heating cooling state

Read, Write 0 - Off

1 - Heat

2 - Cool

3 - Auto

PTTS Get:

pttsg

ptts = 0

OK

SET:

pttss 1

ptts is set to 1

OK

Current temperature Read 0 – 100

Step value = 0.1

PTCT Get:

ptctg

ptct = 10.000000

OK

SET:

ptcts 20

ptct is set to 20.000000

OK

Target temperature Read, Write 10.0 – 38.0

Step value =0.1

PTTT Get:

ptttg

pttt = 20.000000

OK

SET:

pttts 25


80560NT11581A Rev. 1.3 of 46 2017-12-28


Possible values


pttt is set to 25.000000

OK

Temperature display unit

Read, Write 0 - Celsius

1 - Fahrenheit

PTTU Get:

pttug

pttu = 0

OK

SET:

pttus 1

pttu is set to 1

OK

Cooling threshold temperature

Read, Write 10.0 – 35.0

Step value =0.1

PTCTT Get:

ptcttg

ptctt = 15.000000

OK

SET:

ptctts 34

ptctt is set to 34.000000

OK

Current relative humidity

Read 0 – 100

Step value =1

PTRH Get:

ptrhg

ptrh = 10.000000

OK

SET:

ptrhs 50

ptrh is set to 50.000000

OK

Heating threshold temperature

Read, Write 0 – 25.0

Step value =0.1

PTHTT Get:

pthttg

pthtt = 10.000000

OK

SET:

pthtts 20


80560NT11581A Rev. 1.3 of 46 2017-12-28


Possible values


pthtt is set to 20.000000

OK

Target relative humidity

Read, Write 0 -100

Step value =1

PTTRH Get:

pttrhg

pttrh = 10.000000

OK

SET:

pttrhs 25

pttrh is set to 25.000000

OK

gs2k hostless homekit adk application note · gs2k hostless homekit adk application note...

Documents