Quick Start Guide Cypress WICED DevKit

Introduction

In this guide you learn how to use the Arrayent Connect Platform to remotely monitor and control your Broadcom WICED evaluation board over the Internet.

Supported Hardware and Software

The following operating systems are supported:

• Windows 7

The following Broadcom (now Cypress) hardware and software are supported:

• Evaluation Board: BCM9WCD1EVAL1

• WICED Module: BCM943362WCD4

• WICED SDK: 2.4.1

The sample application and the ACA do NOT work with WICED SDK 3.x.x. The sample application and/or Arrayent library may work with other versions of evaluation board, module, or SDK. But Arrayent cannot guarantee or verify this. Arrayent only supports the combination of hardware and software mentioned above.

Getting an Evaluation Board

The Broadcom WICED evaluation board is available for purchase from the following vendors:

• AVNET Express
• Macnica Americas
• Arrow

Setting Up the Application

In this section you learn how to hardcode Wi-Fi and Arrayent credentials into the sample application source code, and then build and download the Arrayent sample application binary onto your evaluation board. You will need a command-line interface (CLI) and a text editor to complete this section. We assume that your CLI supports UNIX-style commands (cd, ls, etc.), or that you know the equivalent commands for your operating system.

1. Open the email that Arrayent sent you containing your DevKit credentials.
2. Inside of the email there is a link to download software. Click the link to download the software.
3. Extract the file. The file that you download will be compressed in Zip format. For sake of example we’ll assume you extract to the following locations:Windows: C:\arrayent\WICED-SDK-2.4.1
4. Open wifi_config_dct.h with a text editor (such as Notepad on Windows). Assuming you extracted the software at the example locations this file would be located at the following location:Windows:

   C:\arrayent\WICED-SDK-2.4.1\Apps\demo\arrayent_monitordemo\wifi_config_dct.h
   

   Now we need to hardcode your Wi-Fi credentials into the source code of the sample application.

5. For the value of CLIENT_AP_SSID enter your Wi-Fi Access Point SSID.
6. For the value of CLIENT_AP_PASSPHRASE enter the passphrase for your Wi-Fi Access Point.
7. Save and close wifi_config_dct.h.The sample application is now hardcoded to connect to this Wi-Fi Access Point. If you ever want to connect to a different Access Point, you will need to modify wifi_config_dct.h and re-compile / re-download the application.
8. Now open main.c. This file is in the same directory as wifi_config_dct.h.
9. Find the implementation of the function setup_arrayent().
10. Replace YOUR_DEVICE_KEY with the device_key value listed in your email from Arrayent.
11. Replace YOUR_DEVICE_NAME with the device_name value listed in your email from Arrayent.
12. Replace YOUR_DEVICE_PASSWORD with the device_password value listed in your email from Arrayent.
13. Check that your values look similar to the following:

    c.device_aes_key = (const char*) "E7E34322115986C1F59E297C667F8FE7";
    c.device_name = (const char*) "1234500500";
    c.device_password = (const char*) "AB";
    

    The exact values that you enter will be different, but each of the three values that you enter should be enclosed in parentheses like the example above.

14. Leave the rest of the values as is.
15. Save and close main.c.The sample application is now hardcoded with these device credentials. If you ever want to change the credentials, you will need to modify the source code and re-compile / re-download the application.
16. Plug in your Broadcom WICED development board to your computer with a USB Mini B cable. Wait a minute to let the device drivers install.If you click on the Installing device driver software popup, you can see the status of the device driver installation. The screenshot below is the result of successful device driver installation.
17. Open a command line interface and change directories to the WICED-SDK-2.4.1 directory.Windows: cdC:\arrayent\WICED-SDK-2.4.1
18. Now execute the following command to build and download the sample application onto your development board.Windows:

    make.exe demo.arrayent_monitordemo-BCM943362WCD4-FreeRTOS-LwIP download run
    

    make.exe is the name of the application that facilitates building the source code and downloading the binary to the board.demo.arrayent_monitordemo indicates the application to build, relative to the Apps directory (the period is a path delimiter, so the application is located at Apps/demo/arrayent_monitordemo. BCM943362WCD4 is the name of the Broadcom WICED module that we are compiling for. FreeRTOS is the name of the operating system that will be running on the board, and LwIP is the networking stack. Last, download and run are special commands that instruct the WICED SDK to download the binary to the board and run it. Upon a successful build and download you will see output similar to the following screenshot:

Configuring the Arrayent Cloud

In this section you use the Arrayent Configurator web application to create a device data model in the Arrayent Cloud. Then you create a Customer Account in the Arrayent Cloud, which you will use later on to monitor and control your device.

Logging In to the Configurator

Follow the instructions below to learn how to log in to the Arrayent Configurator web application.

1. Open a web browser and go to
2. Click Login.

Creating a Device Data Model

In this section you learn how to create a device data model using the Arrayent Configurator web application. In Arrayent terminology a device data model is referred to as a “Device Type”.

Creating the “monitorDemo” Device Type

In this section you learn how to create a device data model using the Arrayent Configuration web application. In Arrayent terminology we call the device data model a “Device Type”. The name of the Device Type we are creating will be called “monitorDemo”.

1. Click the Device Types tab to go to the Device Types page of the Configurator.

This page enables you to create, modify, and delete device data models.

1. Click Add.
   

   

2. For Device Type Name enter monitorDemo.
3. For Device Type Display Name enter monitorDemo.
4. Click Save.

Creating Device Attributes

In this section you use the Configurator to define two Device Attributes, one called led1 and another called gpi1.

1. Look at the Device Types page of the Configurator. You should see two tables. The top table is titled Device Types. The bottom is titled Device Attributes.
2. Click on the row containing our new Device Type, monitorDemo. This should highlight the row in blue.
3. In the bottom table titled Device Attributes click the Add button.
4. Fill out the form so that your new Device Attribute matches the image below. Click Save when finished.
5. Now repeat the process to create another Device Attribute that matches the image below.

See Device Types Guide for a description of how these fields affect a Device Attribute definition.

Creating a Customer Account for Monitor and Control

Follow the instructions in the next section to learn how to use the Configurator to create a new Customer Account in the Arrayent Cloud. Later on you will log in to the Arrayent Cloud as this Customer Account and then monitor and control your evaluation board via the Arrayent Utility web application.

Creating Customer Accounts

The Create Customer Account feature of the Configurator is accessed via the Customer Accounts page. To access that page:

1. Click the Customer Account tab to go to the Customer Account Page of the Configurator.
   

   

Once at the Customer Accounts page, complete the following procedure to create the new Customer Account:

1. Enter the username of the new account in the text field next to Customer Account Name.
2. Select the checkbox. This will enable you to enter text in the textbox next to Customer Account Password.
3. Enter the password of the new account.
4. Leave Master Account Name empty.
5. Enter values for the other user attributes as needed. All attributes other than username and password are optional.
6. Click Save.

When you log in to the Utility app as the new Customer Account, you will need to provide the App ID (A.K.A. System Account ID) of the Customer Account. Customer Accounts inherit the App ID of the System Account that created the account. So if a System Account named “admin” with App ID “10” creates a Customer Account named “user”, the App ID of “user” will also be “10”.

Monitoring and Controlling the Evaluation Board

In this section you use the Arrayent Utility web application to monitor and control your evaluation board.

Logging In to the Utility Application

Follow the instructions below to learn how to log in to the Arrayent Utility web application.

1. Open a web browser and go to the URL below, unless instructed otherwise by Arrayent.

• Read the Architecture Overview to understand how the Arrayent Connect Platform enables connectivity in your devices.
• Check out the source code of the Arrayent sample application to learn how to use the ACA in your own application. Relative to the file that you downloaded from Arrayent, the sample application directory is located at WICED-SDK/Apps/demo/arrayent_monitordemo. Check out the Makefile (arrayent_monitordemo.mk) and the main application source code (main.c) to learn how to include the ACA library into your own project.
• Read the ACA API Reference for complete details on the ACA’s features.
• Read the ACA Developer’s Guide for higher-level guides on implementing a connected device application that uses the ACA.

Appendix

Creating an email alert for led1

If you were stumped on how to create an email alert that is triggered when led1 equals 1, here is the answer:

1. Go to the Utility application.
2. Click the Alerts tab.
3. Click the Add button.
4. Define your alert to match the screenshot below.You need to replace YOUR_EMAIL_HERE with your email address. Device Code should match the device_name value in your email from Arrayent.

Setting up the WICED development environment

We designed our Quick Start Guide to be as painless as possible. The goal is to give you a hands-on demonstration of Arrayent technology, not teach you how to use Broadcom’s IDE and SDK. In this section we provide more instructions on how to set up the WICED IDE. You may encounter problems setting up your environment. Where appropriate, Arrayent will point out relevant Broadcom documentation that may help you, but because these problems are specific to your computer and Broadcom’s software, we will not be able to troubleshoot any problems you encounter in this section. To demonstrate how to use the WICED IDE, we will create a simple sample application that incrementally prints a message to the Arrayent Cloud.

1. Download WICED IDE version 2.4.1. Versions 3.x.x are not currently supported.The file that you download should be called WICED-SDK-2.4.1-IDE-Installer.exe. At the time of writing you can download the Windows version at the following URL: http://community.broadcom.com/docs/DOC-1187. If this URL breaks over time, just log in to community.broadcom.com (registration required) and search for WICED IDE 2.4.1.
2. Double-click on WICED-SDK-2.4.1-IDE-Installer.exe to start the installer.
3. Install the IDE with all of the default settings.
4. Open the WICED IDE.
5. In Project Explorer right-click on WICED-SDK/Apps/Demo and hover over New then select Folder.
6. Name the folder hello_arrayent.
7. In Project Explorer right-click on your new hello_arrayent folder and hover over New then select File.
8. Name the new file hello_arrayent.c.
9. Double-click on hello_arrayent.c. This will open the file in the center window of the IDE (we will call this window the “Editor” window).
10. Copy and paste the following source code into hello_arrayent.c.

    
    // Standard libraries.
    #include 
    #include 
    
    // WICED libraries.
    #include "wiced.h"
    
    // Arrayent libraries.
    #include "aca.h"
    
    int setup_arrayent() {
        arrayent_net_status_t s; // Arrayent network status.
        arrayent_config_t c; // ACA configuration struct.
    
        ArrayentSetConfigDefaults(&c); // Populate with defaults for future compatibility.
    
        // Set these fields with the unique values that Arrayent provided you.
        c.device_aes_key = (const char*) "YOUR_DEVICE_KEY";
        c.device_name = (const char*) "YOUR_DEVICE_NAME";
        c.device_password = (const char*) "YOUR_DEVICE_PASSWORD";
    
        // Leave as is unless instructed otherwise by Arrayent.
        c.device_can_multi_attribute = (uint8_t) 0;
        c.load_balancer_domain_names[0] = (const char*) "devkit-ds1.arrayent.com";
        c.load_balancer_domain_names[1] = (const char*) "devkit-ds2.arrayent.com";
        c.load_balancer_domain_names[2] = (const char*) "devkit-ds3.arrayent.com";
        c.load_balancer_tcp_port = (uint16_t) 80;
        c.load_balancer_udp_port = (uint16_t) 80;
        c.product_aes_key = (const char*) "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF";
        c.product_id = (uint16_t) 1;
    
        // Configure the Arrayent agent with our configuration values.
        if (ArrayentConfigure(&c) != ARRAYENT_SUCCESS) { // See http://goo.gl/uxWQjm
            return EXIT_FAILURE;
        }
    
        // Attempt to connect to the Arrayent Cloud.
        if (ArrayentInit() != ARRAYENT_SUCCESS) { // See http://goo.gl/9kYuzk
            return EXIT_FAILURE;
        }
    
        // Wait for connection.
        do {
            ArrayentNetStatus(&s);
            wiced_rtos_delay_milliseconds(5000);
        }
        while (s.connected_to_server != 1);
    
        return EXIT_SUCCESS;
    }
    
    void get_substring(char source[], char substring[], int start, int end) {
        int index = start;
        while (index < end) {
            substring[index] = source[index];
            index++;
        }
        substring[index] = '\0';
    }
    
    void application_start(void) {
        wiced_time_t time_milliseconds; // Used for seeding PRNG.
        char key[] = "message"; // Name of Device Attribute.
        char value[] = "Hello, Arrayent!"; // Value of Device Attribute.
        const int length = strlen(value) + 1;
        char substring[length]; // Stores incrementally-increasing substrings of value.
        int i = 0; // Index for iterations.
    
        // Init Broadcom WICED stack.
        wiced_init();
    
        // Connect to Wi-Fi Access Point hardcoded in wifi_config_dct.h.
        wiced_network_up(WICED_STA_INTERFACE, WICED_USE_EXTERNAL_DHCP_SERVER, NULL);
    
        if (!wiced_network_is_up(WICED_STA_INTERFACE)) {
            while (1) {
                // Hang.
            }
        }
    
        /* Always seed PRNG before using Arrayent. Below is not production-quality.
         * Contact Arrayent Support for a high-entropy algorithm fit for production. */
        wiced_time_get_time(&time_milliseconds);
        srand(time_milliseconds);
    
        setup_arrayent();
    
        while (1) { // Loop indefinitely.
            /* Incrementally print out "Hello, Arrayent!".
             * Iteration 1: "H"
             * Iteration 2: "He"
             * ... 3: "Hel"
             * ... 4: "Hell"
             * ... 5: "Hello"
             * ...
             */
            while (i < length) {
                get_substring(value, substring, 0, i);
                ArrayentSetProperty(key, substring); // Send attribute update to ACA, which then
                                                     // sends it to Arrayent Cloud.
                wiced_rtos_delay_milliseconds(5000);
                i++;
            }
            if (i >= length) { i = 0; } // From the top!
        }
    }
    Show more
    Show less

11. Modify c.device_aes_key, c.device_name, and c.device_password and save the changes.
12. Now repeat the file creation process and create a new file called wifi_config_dct.h. This file should be in the same folder ashello_arrayent.c.
13. Copy and paste the following source code into wifi_config_dct.h

    /* Copyright 2014, Broadcom Corporation
     * All Rights Reserved.
     *
     * This is UNPUBLISHED PROPRIETARY SOURCE CODE of Broadcom Corporation;
     * the contents of this file may not be disclosed to third parties, copied
     * or duplicated in any form, in whole or in part, without the prior
     * written permission of Broadcom Corporation. */
    #pragma once
    #define CONFIG_AP_SSID "NOT USED FOR THIS APP"
    #define CONFIG_AP_PASSPHRASE "NOT USED FOR THIS APP"
    #define CONFIG_AP_SECURITY WICED_SECURITY_OPEN
    #define CONFIG_AP_CHANNEL 1
    #define SOFT_AP_SSID "NOT USED FOR THIS APP"
    #define SOFT_AP_PASSPHRASE "NOT USED FOR THIS APP"
    #define SOFT_AP_SECURITY WICED_SECURITY_WPA2_AES_PSK
    #define SOFT_AP_CHANNEL 1
    #define CLIENT_AP_SSID "YOUR_WI-FI_SSID"
    #define CLIENT_AP_PASSPHRASE "YOUR_WI-FI_PASSPHRASE"
    #define CLIENT_AP_BSS_TYPE WICED_BSS_TYPE_INFRASTRUCTURE
    #define CLIENT_AP_SECURITY WICED_SECURITY_WPA2_MIXED_PSK
    #define CLIENT_AP_CHANNEL 1
    #define CLIENT_AP_BAND WICED_802_11_BAND_2_4GHZ
    #define WICED_COUNTRY_CODE WICED_COUNTRY_UNITED_STATES
    

14. Modify CLIENT_AP_SSID and CLIENT_AP_PASSPHRASE and save the changes.
15. Create another new file. Name it hello_arrayent.mk.
16. Copy and paste the following source code into hello_arrayent.mk.

    # Copyright 2014, Broadcom Corporation
    # All Rights Reserved.
    # This is UNPUBLISHED PROPRIETARY SOURCE CODE of Broadcom Corporation;
    # the contents of this file may not be disclosed to third parties, copied
    # or duplicated in any form, in whole or in part, without the prior
    # written permission of Broadcom Corporation.
    NAME := hello_arrayent
    $(NAME)_SOURCES := hello_arrayent.c
    # Libraries to include.
    # Directories must be relative to WICED SDK Libraries directory.
    # E.g. /home/john/WICED-SDK-2.4.1/Library/arrayent/libaca_wiced
    $(NAME)_COMPONENTS := arrayent/libaca_wiced
    # Magic Wi-Fi configuration file. It appears to need this exact name
    # or else WICED's makefile will complain.
    WIFI_CONFIG_DCT_H := wifi_config_dct.h
    

17. In the Make Target window right-click on Wiced-SDK and left-click New.
18. For Target Name enter demo.hello_arrayent-BCM943362WCD4-FreeRTOS-LwIPdownloadrun.
19. Leave the other options as is.
20. Click OK.
21. When you received your DevKit you downloaded software from Arrayent. Open that folder and drag the contents ofLibrary/arrayent into the Library folder of your WICED IDE.
22. Plug in your development board to your computer with a USB Mini B cable.
23. In the Make Target window double-click on your new Make target. The WICED IDE will compile the application and download it to your development board.
24. Log in to the Configurator and add the following Device Attribute to your monitorDemo Device Type.
25. Log in to the Utility application and monitor your device. You should see the value of the message attribute updating every 5 seconds.