GS2K Hosted HomeKit User Guide
1VV0301439 Rev. 1.4 – 2019-01-16
GS2K Hosted HomeKit User Guide
SPECIFICATIONS ARE SUBJECT TO CHANGE WITHOUT NOTICE 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. COPYRIGHTS
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. COMPUTER SOFTWARE COPYRIGHTS
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.
1VV0301439 Rev. 1.4 Page 2 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
USAGE AND DISCLOSURE RESTRICTIONS
I. License Agreements
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. II. Copyrighted Materials
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 III. High Risk Materials
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. IV. Trademarks
TELIT and the Stylized T Logo are registered in Trademark Office. All other product or service names are the property of their respective owners. V. Third Party Rights
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.
1VV0301439 Rev. 1.4 Page 3 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
APPLICABILITY TABLE
PRODUCT
GS2K based Modules
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.
1VV0301439 Rev. 1.4 Page 4 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Revision History
Version Date Remarks
1.0 November Initial release 2016 1.1 April, 2017 Restructuring the content and updated scripts
• Updated Chapter 2 Building Hosted HomeKit Using SDK Builder Tool with HomeKit iCloud services. 1.2 October, 2017 • Updated 3.2.1 Download and Install Python for Windows section. • Added Appendix C Hosted HomeKit over iCloud section.
September, Added a note regarding iCloud testing under section Appendix C 1.3 2018 Hosted HomeKit over iCloud and updated the AT command.
1.4 January, 2019 Added Appendix D Creating Software Token using PHP Script.
1VV0301439 Rev. 1.4 Page 5 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Table of Contents
NOTICE……… ...... 2
COPYRIGHTS...... 2
COMPUTER SOFTWARE COPYRIGHTS ...... 2
USAGE AND DISCLOSURE RESTRICTIONS ...... 3
APPLICABILITY TABLE ...... 4
CHAPTER 1 INTRODUCTION ...... 10
CHAPTER 2 BUILDING HOSTED HOMEKIT USING SDK BUILDER TOOL ...... 11
CHAPTER 3 TESTING HOSTED HOMEKIT IN SERIAL TO WI-FI APPLICATION ...... 15
3.1 PREREQUISITES ...... 16 3.2 TEST PROCEDURE ...... 16 3.2.1 Download and Install Python for Windows ...... 17 3.2.2 Configuring GainSpan’s Python Scripting Package ...... 19 3.2.3 Running Python Script to Simulate Host MCU ...... 20 3.2.4 Testing Hosted HomeKit using iOS Home Application ...... 22 APPENDIX A BUILDING HOSTED HOMEKIT IN S2W APPLICATION ...... 31
A.1 PREREQUISITES ...... 31 A.2 DOWNLOADING HOMEKIT PACKAGE FROM SDK BUILDER ...... 31 A.3 UPDATING AND BUILDING SDK_LIB.EWW WORKSPACE ...... 33 A.4 UPDATING AND BUIDLING S2W.EWW WORKSPACE ...... 35 APPENDIX B PROGRAMMING GAINSPAN MODULE ...... 39
APPENDIX C HOSTED HOMEKIT OVER ICLOUD ...... 42
APPENDIX D CREATING SOFTWARE TOKEN USING PHP SCRIPT ...... 44
D.1.1 PREREQUISITES ...... 44 D.1.2 PROCEDURE ...... 44
1VV0301439 Rev. 1.4 Page 6 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
List of Figures
Figure 1: Telit Wi-Fi Portal Login ...... 11
Figure 2: Accessing SDK Builder Tool ...... 12
Figure 3: SDK Builder Configuration ...... 13
Figure 4: Selecting HomeKit Feature ...... 13
Figure 5: Creating Final Build ...... 14
Figure 6: Upon Successful Build ...... 14
Figure 7: Test Setup ...... 15
Figure 8: COM Port Selection ...... 16
Figure 9: Downloading Python for Windows ...... 17
Figure 10: Python Installer for Windows ...... 18
Figure 11: Installing Python for Windows ...... 18
Figure 12: Checking Python version ...... 19
Figure 13: Installing pyserial ...... 19
Figure 14: Configuring GainSpan’s Python Scripting Package ...... 20
Figure 15: Running test script ...... 21
Figure 16: Connecting to AP ...... 22
Figure 17: Adding Accessory ...... 23
Figure 18: Fan Service ...... 24
Figure 19: Set up code ...... 25
Figure 20: Successful addition of Accessory ...... 26
Figure 21: Favorite Accessory Screen ...... 27
Figure 22: Switching ON the Accessory ...... 28
Figure 23: Opening the Fan Switch ...... 29
Figure 24: FAN Speed ...... 30
Figure 25: SDK Builder ...... 31
Figure 26: HomeKit ADK Build ...... 32
Figure 27: Updating rom_patch_fpt.ewp...... 33
Figure 28: Rebuilding sdk_lib.eww ...... 34
Figure 29: Changing Post-build command line ...... 36
Figure 30: Changing Command line options ...... 37
1VV0301439 Rev. 1.4 Page 7 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Figure 31: HomeKit.a and wac.a files in applet_1.ewp ...... 38
Figure 32: Rebuilding s2w.eww ...... 38
Figure 33: Communicating with GainSpan ...... 39
Figure 34: Valid Super Block and Firmware Single Image Selected ...... 40
Figure 35: Programming Single Image Complete ...... 41
Figure 36: Example of generated CSR using KEY tool ...... 45
Figure 37: Example of an PEM file ...... 45
1VV0301439 Rev. 1.4 Page 8 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
List of Tables
Table 1: Prerequisites ...... 16
Table 2: Entries for Python Fan Accessory ...... 21
1VV0301439 Rev. 1.4 Page 9 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Chapter 1 Introduction
This document provides test procedure for demonstrating hosted HomeKit feature in Serial-to- Wi-Fi Application. It also provides step by step procedure to build the hosted HomeKit feature in Serial-to-Wi-Fi Application.
1VV0301439 Rev. 1.4 Page 10 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Chapter 2 Building Hosted HomeKit Using SDK Builder Tool
This section provides detailed procedure to create custom package of Serial to Wi-Fi Application with HomeKit feature using SDK Builder tool.
NOTE:
• The user should have HomeKit ADK license and Apple’s MFI license to enable the HomeKit feature in Serial to Wi-Fi application. • In the below snapshots the numbering indicates the sequence of progress.
Following are the steps to enable the HomeKit feature in Serial to Wi-Fi application:
1. Login to Telit Wi-Fi Portal (https://wifi.telit.com/secure/login ) using your registered “Email” and “Password”.
Figure 1: Telit Wi-Fi Portal Login
2. Start SDK Builder tool by selecting SDK BUILDER and option “GS2000” on the right hand corner of Home screen as shown in following screen shot.
1VV0301439 Rev. 1.4 Page 11 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Figure 2: Accessing SDK Builder Tool
3. Select SDK Builder configuration based on GainSpan’s module (GS2200, GS2101, and so on). Following screenshot shows custom selection of Serial to Wi-Fi Application firmware, for GS2200 module.
NOTE: Ensure “Include Documents & Utilities" check box is selected.
1VV0301439 Rev. 1.4 Page 12 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Figure 3: SDK Builder Configuration
4. Proceed by clicking the “Next” button, keep selecting the “Next” option until the “Network Services” tab is found. Select “HomeKit” and “iCloud” (to enable iCloud services).
Figure 4: Selecting HomeKit Feature
5. Keep selecting the “Next” option until the “Summary” tab, scroll down and click “OK” button. Build button will be enabled, click “Build” button to generate the Firmware Package.
1VV0301439 Rev. 1.4 Page 13 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Figure 5: Creating Final Build
6. Once the package is successfully built, an email is sent to the registered email account. Now, download the package from the SDK Builder tool under “Build History” Tab.
Figure 6: Upon Successful Build
7. Make GS2K Evaluation board ready for HomeKit demonstration, by programing the GS2K module with custom firmware downloaded in above step.
NOTE: If not familiar in programming GainSpan module, please refer Appendix: Programming GainSpan Module.
1VV0301439 Rev. 1.4 Page 14 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Chapter 3 Testing Hosted HomeKit in Serial to Wi-Fi Application
This section describes how to test Hosted HomeKit feature using Serial to Wi-Fi Application.
NOTE: In the below snapshots the numbering indicates the sequence of progress.
Following figure shows Test Bed and Pre-requisites for demonstrating the GainSpan’s Hosted HomeKit feature using Serial-to-Wi-Fi Application.
Figure 7: Test Setup
1VV0301439 Rev. 1.4 Page 15 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
3.1 PREREQUISITES The prerequisites for testing a Hosted HomeKit application is as below:
Hardware and Software Description 1. GainSpan Evaluation board with This Evaluation Board is used for running Serial to Wi-Fi WAC chip Application firmware with HomeKit feature. The EVB communicates with iOS Device Via Access Point and receives HomeKit request from Wi-Fi Interface and passes the requests to Python scripts running on Windows Laptop via Serial Interface. The response from the python scripts are received as HomeKit responses via Wireless Interfaces.
2. USB Connector Cable The connector is used for serial connection between GainSpan Evaluation board and Windows Laptop. 3. Windows Laptop with Python This script is used for simulating MCU’s behavior. Software (3.5.2 onwards) Installed. 4. Access Point An Access Point is used for establishing Wireless Local Area Network. GainSpan evaluation board and iOS device communicates using this Access Point. 5. Apple Device with iOS 10 onwards This device is used to run the “Home” App for testing HomeKit Feature. Table 1: Prerequisites 3.2 TEST PROCEDURE 1. Connect one end of USB connector to GS2200 EVB’s USB0 Port and other end of the connector to Laptop’s USB Port. 2. Get the COM port number from Device Manager at Ports (COM & LPT), it is required for executing scripts.
Figure 8: COM Port Selection 1VV0301439 Rev. 1.4 Page 16 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
3. Configure the GainSpan module in Auto connection mode to run the script. Flash the firmware on GainSpan module and keep the module in run mode.
Connect the teraterm terminal to execute the following “Auto Connection” commands. The default baud rate for UART interface is 9600.
at+ncmauto=0,0,0 at&w0 at&y0 at+reset 4. To check the version of the python software, type the command “Python -V” in the command prompt. Ensure that python version is 3.5.2 or Onward. If Python Software is not installed in the laptop, please follow the steps mentioned in “Download and Install Python for Windows”. 5. Run the Python Script as explained in “Configuring GainSpan’s Python Scripting Package “ 6. This script will ask the user to enter the COM port number, Wireless Network Name (SSID) and Passphrase. 7. GS2200 connects to the configured Access point. 8. Connect iPhone to the same Access Point where GS2200M EVB is connected. 9. Perform the HomeKit Test as explained in section “Testing Hosted HomeKit using iOS Home Application”.
3.2.1 Download and Install Python for Windows
Perform the following steps to download python for windows:
1. Go to URL: https://www.python.org/downloads/ 2. Download latest version of Python package and click on Download. This will navigate to other pages
Figure 9: Downloading Python for Windows
1VV0301439 Rev. 1.4 Page 17 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
3. Scroll down and download the package based on the windows Operating System type ( 32 Bit/64 Bit).
Figure 10: Python Installer for Windows
4. Install the downloaded Python. Ensure the check box is selected for “Add Python 3.5 to PATH “during the installation process.
Figure 11: Installing Python for Windows
1VV0301439 Rev. 1.4 Page 18 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
5. After successful installation of Python, check the version by executing the following command from the command prompt. Python –V
Figure 12: Checking Python version
6. As serial interface module is not available in default Python installation. Install “pyserial” module by executing following command from the command prompt. Pip install pyserial
Figure 13: Installing pyserial
3.2.2 Configuring GainSpan’s Python Scripting Package
Perform the following steps to set GainSpan’s Python scripting package:
1. Navigate to “~\Tools\scripts” folder location in the downloaded SDK package from SDK Builder. File “pyGate.zip” will be listed, right-click on “pyGate.zip” file and do “Extract to pyGate”. 2. Open the system properties by pressing the Windows key + R on keyboard, type “sysdm.cpl” and click “OK”. 3. Choose “Advance” tab and opt “Environment Variable”. 4. Now click on the option “New”, to add the “Environment Variable” with the following details as shown in the figure below and click “OK”. Variable Name: PYTHONPATH
1VV0301439 Rev. 1.4 Page 19 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Variable Value: D:\Tools\scripts\pyGate
NOTE: In the above step-4 and in the figure below the variable value is set to D:\Tools\scripts\pyGate path. As the package is copied and extracted in “D:\” folder.
Figure 14: Configuring GainSpan’s Python Scripting Package
3.2.3 Running Python Script to Simulate Host MCU
“fanaccessory.py” is the test script written in python programming language. This script simulates the MCU’s behavior.
When Apple Device request fan accessory information over the Wi-Fi interface, GainSpan Module receives the request and sends it to the serial interface. “fanaccessory.py” receives these requests over serial interface, prepares the required response, and sends it back to GainSpan Module over the serial interface.
GainSpan module processes these inputs from serial interface, prepares the response in JSON format, and sends it over Wi-Fi interface to Apple device.
From the windows command prompt, navigate to “D:\Tools\scripts\pyGate\pyGate\scripts\regr\homeKit”, and execute the following command. The script would ask user to enter following Python fanaccessory.py
1VV0301439 Rev. 1.4 Page 20 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Parameters Description Port number UART COM Port number is displayed in the Device Manager with ports (COM & LPT) (refer Image Figure 8: COM Port Selection). Give the COM Port number only. For example: - for COM13, give port number as “13” not “COM13” Wireless Networks SSID SSID of the local Access Point. Passphrase It is the Passphrase of the local Access Point, if present. If not just press the “ENTER” on the key board. Table 2: Entries for Python Fan Accessory
Figure 15: Running test script
1VV0301439 Rev. 1.4 Page 21 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
3.2.4 Testing Hosted HomeKit using iOS Home Application Perform the following steps to test the Hosted HomeKit feature using iOS Home Application:
1. Connect the iDevice to the same AP to which GS Node is connected.
Figure 16: Connecting to AP
1VV0301439 Rev. 1.4 Page 22 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
2. Launch the Home Application in the iPhone and tap “Add Accessory”.
Figure 17: Adding Accessory
1VV0301439 Rev. 1.4 Page 23 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
3. Tap on the displayed Fan service.
Figure 18: Fan Service
1VV0301439 Rev. 1.4 Page 24 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
4. Home Application requests for an 8-digit set up code. Tap “Enter code manually” and Enter the 8-digit code “101-48-505”.
Figure 19: Set up code
5. After entering the code, pairing procedure starts from the iPhone to GS Node.
1VV0301439 Rev. 1.4 Page 25 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
6. Following screen is displayed upon successful addition of Accessory followed by Accessory details screen.
Figure 20: Successful addition of Accessory
1VV0301439 Rev. 1.4 Page 26 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
7. Tap “Done”. Home Application displays the Favorite Accessory screen where it shows the fan state as OFF.
Figure 21: Favorite Accessory Screen
1VV0301439 Rev. 1.4 Page 27 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
8. Tap GS-FAN accessory to switch ON the accessory.
Figure 22: Switching ON the Accessory
1VV0301439 Rev. 1.4 Page 28 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
9. Long press on the GS-FAN to open the Fan Switch.
Figure 23: Opening the Fan Switch
1VV0301439 Rev. 1.4 Page 29 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
10. Speed of the FAN can be increased or decreased by sliding UP/DOWN on the screen.
Figure 24: FAN Speed
1VV0301439 Rev. 1.4 Page 30 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Appendix A Building Hosted HomeKit in S2W Application
NOTE: In the below snapshots the numbering indicates the sequence of progress.
A.1 PREREQUISITES
Following are the pre-requisites required for building a Hosted HomeKit application:
1. IAR Workbench with valid license 2. SDK Builder with SDK+HomeKit ADK access.
A.2 DOWNLOADING HOMEKIT PACKAGE FROM SDK BUILDER
Perform the following steps to download HomeKit package: 1. Login to https://wifi.telit.com/secure/login and go to SDK Builder page.
Figure 25: SDK Builder
2. Select the following configuration as part of the HomeKit ADK package and click Build.
1VV0301439 Rev. 1.4 Page 31 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Figure 26: HomeKit ADK Build
3. Once the package is successfully built, an email is sent to the registered email account. 4. Download the package and extract it.
To build Hosted HomeKit feature in Serial-to-Wi-Fi Application, 1. Update and build the sdk_lib.eww workspace (from the downloaded and extracted HomeKit SDK package) 2. Update and build the s2w.eww workspace (from the downloaded and extracted HomeKit SDK package)
1VV0301439 Rev. 1.4 Page 32 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
A.3 UPDATING AND BUILDING SDK_LIB.EWW WORKSPACE
Perform the following steps to update and build sdk_lib.eww:
1. Go to path (from the downloaded and extracted folder) \SDK\Embedded\ geps\build\ and find sdk_lib.eww Note: By defualt “sdk_lib.eww” comes up with all the generic features to evaluate Gainspan Firmware. When HomeKit feature is included, it exceeds the GainSpan supported firmware size as Homekit has its own set of features. Configure the ROM patch function pointer table project “rom_path_fpt.ewp” with set of features those are required for building Hosted Homekit Application. 2. To update “rom_path_fpt.ewp”, open “sdk_lib.eww” workspace. This worksapce has 3 projects attached to it. Select “rom_patch_fpt.ewp” right click and select Options Under category, select C/C++ Compiler Naviate to Pre-processor tab Under “Defined Symbols” Remove all Macros and set the Macros mentioned as follows.
Figure 27: Updating rom_patch_fpt.ewp
Following is the list of Macros required for Hosted HomeKit: GSN_CLK_CTL_ENABLE GSN_DYN_MEM_MGMT_ENABLE GSN_GPIO_ENABLE GSN_MDNS_SD_ENABLE GSN_PSP_ENABLE GSN_XML_STRING_PARSER_ENABLE GSN_MB_ENABLE GSN_SAFE_FLASH_ENABLE GSN_FACT_DFLT_ENABLE GSN_HTTPD_SYS_API_ENABLE GSN_FLASH_CACHE_ENABLE GSN_HTTP_ENABLE GSN_NWX_ENABLE 1VV0301439 Rev. 1.4 Page 33 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
_RPST_= const GSN_SECURITY_ENTERPRISE_AVAILABLE GSN_DHCP_SERVER_ENABLE GSN_XML_PARSER_ENABLE GSN_I2C_ENABLE GSN_OTP_MM_ENABLE GSN_SOFT_TIMER_ENABLE GSN_OAL_ENABLE _DLIB_FILE_DESCRIPTOR GSN_DMA_ENABLE GSN_UART_ENABLE TX_ENABLE_IAR_LIBRARY_SUPPORT GSN_NETX_ENABLE GSN_SYS_QUAL_ENABLE GSN_OTP_ENABLE GSN_SYS_CTL_ENABLE GSN_HTTP_SERVER_ENABLE GSN_WDD_ENABLE GSN_PERSIST_TIMER_ENABLE GSN_SDAADC_ENABLE IAR GSN_FLASH_IF_ENABLE
3. Press “F8” key on key board, “batch Build” pop up is displayed. Click “Rebuild All” button.
Figure 28: Rebuilding sdk_lib.eww
1VV0301439 Rev. 1.4 Page 34 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
A.4 UPDATING AND BUIDLING S2W.EWW WORKSPACE
Perform the following steps to update and build s2w.eww:
1. Go to "\SDK\Embedded\userapps\s2w\build" and open "pre_include.h". 2. Remove all the content from "pre_include.h" and replace with following HomeKit macros: #define TX_ENABLE_IAR_LIBRARY_SUPPORT #define IAR #define FIXED_ROM_BUILD #define NX_INCLUDE_USER_DEFINE_FILE #define TM_USE_HTTPD #define S2W_GSLINK #define S2W_GSLINK_XML #define S2W_WEB_SERVER #define S2W_UART_ENABLE #define S2W_FORCE_UART_PORT #define S2W_DEFAULT_UART_BAUD 9600 #define S2W_DEFAULT_UART_BITS_PER_CHAR 3 #define S2W_DEFAULT_UART_PARITY 0 #define S2W_DEFAULT_UART_STOP_BITS 0 #define S2W_DEFAULT_UART_SW_FLOW 0 #define S2W_DEFAULT_UART_HW_FLOW 0 #define S2W_DNS_CLIENT #define S2W_MDNS_ENABLE #define S2W_NCM_SUPPORT_ENABLE #define S2W_NCM_ROAMING_SUPPORT #define S2W_HOMEKIT_SUPPORT #define S2W_I2C_SUPPORT #define S2W_ADC_SUPPORT #define RUN_ALL_FROM_FLASH #define NX_INCLUDE_USER_DEFINE_FILE #define S2W_WEB_FS_AVAILABLE #define S2W_EXTFLASH_DRIVER_TEST #define S2W_MEM_ACCESS #define S2W_PERSISTENT_TMR_SUPPORT #define S2W_DHCP_SERVER_ENABLE 3. Open the S2W Application's workspace ("s2w.eww") located at "\SDK\Embedded\userapps\s2w\build" 4. Two projects "s2w" and "applet_1" are displayed in the WorkSpace. 5. Go to Workspace --> Select "s2w" project --> right click --> select Options. This opens the "Options for node S2W" window. 6. Under Category -->go to "Build Actions" --> change content of "Post-build Command Line :" with following content: "$PROJ_DIR$\symbols_homekit.bat" "$TOOLKIT_DIR$\bin" "$PROJ_DIR$"
1VV0301439 Rev. 1.4 Page 35 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Figure 29: Changing Post-build command line
7. Under Category -->go to "Linker" -->go to "Extra Options" tab -->change content of "Command Line Options : (One per Line)" with following: -f $PROJ_DIR$\..\..\..\geps\lib\rom_patch_fpt_symbols.txt -f $PROJ_DIR$\s2wKeepSymbols_homekit.txt --keep app_auto_patch_dummy1 --keep app_auto_patch_dummy2 --entry GsnStartup_Main --redirect malloc=MALLOC --redirect free=FREE
1VV0301439 Rev. 1.4 Page 36 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Figure 30: Changing Command line options
8. Add two Library files “homekit.a” and “wac.a” to “applet_1.ewp” project. 9. Select “applet_1” project, right click and select the Add option with “Add files…”. This opens the “Add Files window”. 10. Choose “All Files” and select the library files “homekit.a” and “wac.a” from "\SDK\Embedded\adk\HomeKit\lib” and “\SDK\Embedded\adk\wac\lib" paths respectively.
1VV0301439 Rev. 1.4 Page 37 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Figure 31: HomeKit.a and wac.a files in applet_1.ewp
11. Press “F8” key on the key board and “batch Build” window pops up. Click “Rebuild All” button to build the project without any errors.
Figure 32: Rebuilding s2w.eww
12. Navigate to "\SDK\Embedded\userapps\s2w\build” and RUN “flash_program_FlashFetch_SingleImage.bat” file. 13. Press the Enter key after providing the COM port details. 14. Single image “gs2000_SingleImage.bin” will now be created in “\SDK\Embedded\userapps\s2w\bin” folder.
1VV0301439 Rev. 1.4 Page 38 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Appendix B Programming GainSpan Module
For programming the GS2101M and GS2200M modules using UART interface, perform the following:
1. Select the Single UART Interface from the pull-down tab. 2. Select the UART port. 3. Select Baud Rate. The Baud Rate 115200 will automatically be selected. When selecting 921600 Baud Rate. Ensure Jumper J13 is shorted, it is located near to Programming and Running Switch. 4. Click the Check Connection button. The software will communicate with the GS2101M or GS2200M evaluation board to check the connection and display the Module Specifications (Module Type and Mac Address of the module). A Green check will display at the bottom of the screen indicating the Connection and Communication with the board is successful along with the selections as show below:
Figure 33: Communicating with GainSpan
5. Select the Firmware and Binaries to program the board with a Single Image. Click the Browse (...) button next to the “Super Block” and “Current FW Version”. Select the Super Block and Single Image Firmware located in “\Embedded” folder in the downloaded package.
1VV0301439 Rev. 1.4 Page 39 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
6. Once selected, a message will be displayed indicating that a valid Super Block and Firmware Image have been selected as seen below:
Figure 34: Valid Super Block and Firmware Single Image Selected
7. Click the “Erase and Program" button. The GUI software will go through a process of programming the module flash with the new firmware and binaries. When completed, a Green check will be displayed indicating the flash has been programmed successfully which is as shown below:
1VV0301439 Rev. 1.4 Page 40 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Figure 35: Programming Single Image Complete
8. Click the “Close” button. Turn the ON/OFF switch to the OFF position. Turn the PROGRAM/RUN switch to the RUN position. Turn the ON/OFF switch back to the ON position.
1VV0301439 Rev. 1.4 Page 41 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Appendix C Hosted HomeKit over iCloud
With iCloud enabled, we can use the same to remotely access control of iOS-connected home automation accessories and not confined to be on the local network only.
To enable it we perform following modifications in at+hksetup command at host side: at+hksetup=3,HK-GS2000-S2W,1,GS2000,101-48-505,ffffffff,1
‘fffffff’ is put to enable for all event notifications available.
Following event notifications are applicable for iCloud:
iCLOUD ACTIVATION INIT 16
iCLOUD ACTIVATION DONE 17
iCLOUD ACTIVATION FAILED 18
iCLOUD PAIRING INIT 19
iCLOUD PAIRING DONE 20
iCLOUD PAIRING FAILED 21
iCLOUD CONNECTED 22
iCLOUD DISCONNECTED 23
iCLOUD VERIFICATION INIT 24
iCLOUD VERIFICATION DONE 25
iCLOUD VERIFICATION FAILED 26
iCLOUD VERIFICATION SESSION CLOSED 27
iCLOUD ACCESSORY DISCOVERY REQ 28
iCLOUD CHAR READ REQUEST 29
iCLOUD CHAR WRITE REQUEST 30
iCLOUD CHAR EVENT REQUEST 31
1VV0301439 Rev. 1.4 Page 42 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
These notifications are received on the terminal as and when these events are triggered.
All the procedures are same as mentioned in the document.
Note: In iOS 11.0, iCloud activation may fail. Solution is, during ICLOUD ACTIVATION INIT - go to settings of “iDevice” and select “Home” icon. Toggle “Use this iPad as a Home Hub” option such a way that it is disabled at the end of toggling.
Once the event notification “iCLOUD ACCESSORY DISCOVERY REQ” is received i.e. no. 28, change the iDevice network to something other than home network and it can still control the accessories through homeKit app. Introduction.
The iCloud testing requires ECC enabled firmware. Therefore, it is mandatory for the customer to enable "ECC related feature" in the HomeKit "s2w" Project while building the S2W application.
1VV0301439 Rev. 1.4 Page 43 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Appendix D Creating Software Token using PHP Script
HomeKit enabled accessories can authenticate using software-based authentication in iOS 11.3 or later. This method uses a rolling token scheme to authorize an accessory to work with HomeKit.
NOTE: Below steps are based on “Home Kit Software Authentication Server Specification” provided by Apple.
User can make use of the below script or follow it as a reference to create their own using their choice of language.
D.1.1 PREREQUISITES
• The licensee must have an approved MFI product plan before initiating a token request. • Product Plan ID (PPID) - “xxxxxx-xxxx” must be known to be used across the script. • MFI certificate must be kept handy. • The system should be equipped with environment setup required to run PHP scripts. Environmental Setup
• Download and install XAMPP web server (for running Apache) • Generator java key and convert .jks to .key file to support PHP curl request • Run the API through PHP script provided (localhost/api_request.php)
D.1.2 PROCEDURE
Perform the following steps to create software token-based authentication using PHP script.
Step 1: Create and place the “homekitR12.key” in the same directory as the script files. When the script is run it fetches the .key file from the directory and generate the Certificate Signing Request (CSR).
The following example illustrates how to generate CSR using KEY tool: keytool -genkeypair -keystore
keytool -certreq -keystore
1VV0301439 Rev. 1.4 Page 44 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Figure 36: Example of generated CSR using KEY tool
Step 2: Send the generated CSR file for Apple validation.
• Licensee must send the CSR to [email protected] indicating if the request is for staging or production. The email subject used should be "Software Authentication Staging CSR setup - [MFi account number]” or “Software Authentication Production CSR setup - [MFi account number]” as appropriate. • Apple will validate the CSR and provide a client certificate for the respective CSR that must be used for communicating with the Apple Server. • Licensee server must trust the DigiCert EV SSL certificate. • Upon successful interoperability of the staging server, execute the test cases as listed in the Addendum of “HomeKit Software Authentication Server Specification” document and send the test results to [email protected].
Step 3: After a successful authorization, user receives the “MFI-xxxxxx.cert.pem” PEM file. This file must be placed in the same folder as the script file. When the script is run, it fetches it from the directory.
Figure 37: Example of an PEM file 1VV0301439 Rev. 1.4 Page 45 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Step 4: Choose the appropriate URL depending on the server type used previously during CSR generation.
Staging URL : https://sauth-external-staging.apple.com/ (default configuration) Production URL: https://sauth-external.apple.com/
Step 5: All entries in the script with "ppid" => "246035-0025" must be modified with the user PPID.
Except for in line 236, where we give a dummy PPID:
$data["ppid"] = "123456-1234";
Step 6: The script will run in your local host PHP server setup (http://localhost/homekit_api/api_request.php)
Output from PHP Script
Once the Script runs fine and makes all Restful API requests successfully, you will observe an output with the token details as shown below:
1VV0301439 Rev. 1.4 Page 46 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
Below is the list of set of logs belonging to each step performed in the script:
*****************Apple API Starting*******************
1. API For Bulk Request Authentication
*********START BLUK Request Auth Entities **********
Request URL: https://sauth-external-staging.apple.com/api/v1.0/external/authEntityRequests
Request Param: {"ppid":"100000-1000","requested_auth_entity_count":"1"}
Response: {"request_id":"70ffbed9-c48d-4afa-bfd2- 72b96ee9db4d","download_availability":"2018-08-30 13:46:00.0"}
*********END BLUK Request Auth Entities **********
2. Download Auth Entities *********START Download Auth Entities **********
Request URL: https://sauth-external- staging.apple.com/api/v1.0/external/authEntities/70ffbed9-c48d-4afa-bfd2-72b96ee9db4d
Request Param: None
Response: {"file_count":1,"file_name":["70ffbed9-c48d-4afa-bfd2- 72b96ee9db4d_1535633161281.csv"]}
*********END Download Auth Entities **********
3. Download the software token files. *********START Download Files **********
Request URL: https://sauth-external- staging.apple.com/api/v1.0/external/authEntities/70ffbed9-c48d-4afa-bfd2- 72b96ee9db4d/70ffbed9-c48d-4afa-bfd2-72b96ee9db4d_1535633161281.csv
Request Param: None
Response: 123456- 1234,1EC33WC4F9E5646B8BCEABA672D7N984,MYGpME4CAQEA/gEBBAju2lAIYQEAAB NDFSGsc901BNDwrhjk034QIOP8999wq4rff5666DAU/AgIAyQIBAQQLMAX7bng2sVCjYyND A0LTAwMDUwGAIBZwIBAQQQj7gCmP9/RFmM8QrmBQ3KgQ==,1b8v46faf09
*********END Download Files **********
4. Register the software token with Apple Server: Single software token only.
*********START Single Auth Entity **********
Request URL: https://sauth-external-staging.apple.com/api/v1.0/external/single/usedAuthEntities
Request Param: {"ppid":"123456-1234","uuid":"c552-c51b-4576-aec3- 2edcb853709e","auth_entity":"1EC33WC4F9E5646B8BCEABA672D7N984"}
Response: 200 – OK
*********END Single Auth Entity **********
1VV0301439 Rev. 1.4 Page 47 of 49 2019-01-16 GS2K Hosted HomeKit User Guide
5. Check the status of the registration process.
*********Query Request Results**********
Request URL: https://sauth-external-staging.apple.com/api/v1.0/external/status/70ffbed9- c48d-4afa-bfd2-72b96ee9db4d
Request Param: None
Response: {"request_status":"Completed","success_count":1,"error_entities":{"EXT_SVC_2014":["A9CC9 E9E1B2B4CA1A2962E49D6640C89"]}}
*********Query Request Results**********
*****************Apple API Ending*******************
1VV0301439 Rev. 1.4 Page 48 of 49 2019-01-16