Filter results by

ZigBee

ARTIK 5/7/10 and ARTIK 030 modules offer as standard the ZigBee®/Thread personal area network interface, using a built-in IEEE 802.15.4 radio. ZigBee is used primarily for control and monitoring of lights, sensors, switches, appliances, etc. and can be applied to both home and commercial/industrial automation.

The low-power ZigBee system allows devices within range of each other to autonomously form a "mesh" network that may include "star" grouping for endpoints.

Sleepy End Devices
Simple, battery-operated devices (like temperature sensors) form a star around a central parent device that routes their messages into the main mesh. These end devices wake up on their own schedule, check messages from / send status to their parent, and go back to sleep.
Powered End Devices
Line-powered devices or devices with higher-capacity or rechargeable batteries are used when immediate reaction is required (a controllable light, for example). These devices are typically router-capable.
Router capability
Router-capable devices can take part in a mesh and can be dynamically coordinated to select routes. Routers must stay active all the time and therefore are often line-powered.
Coordinator
One of these router devices becomes Coordinator for the system and orchestrates forming / maintaining / reorganizing the network, and rerouting message travel paths as needed to adapt to changing conditions (device addition/removal, radio disturbances).

By using this hybrid topology, the range of the network between the most distant endpoints is extended considerably, with communication packets travelling by "hops" along the best route.

Nearly all ZigBee devices on the market (even "end" devices) act as routers. You'll also see that coordinators take over join operations even when you initiate them from an intermediate router.

ZigBee Application Tutorial

This tutorial makes use of the ZigBee software stack that is part of the Simplicity Studio® 4.0 development installation (see Prerequisites). The Simplicity tool generates custom source code according to the features you select. The code stack is the same across all ARTIK module ZigBee circuits, so you can expect consistent ZigBee programming.

When it comes to actually compiling the generated files, the approach differs depending on whether the application is Linux-based.

ARTIK 030 applications. Being designed for low-cost and CPU-efficient applications, the ARTIK 030 is not Linux-based. Its memory and processing capabilities are not sufficient for native compilation of code, so cross-compilation takes place on a separate PC.

  • To simply explore the device capabilities discussed in this tutorial, you can use pre-compiled images we have prepared for you to upload.

  • When you're ready to create custom ARTIK 030 applications, you'll use Simplicity Studio. You'll also need to install a cross-compile toolchain to compile the code on your development PC. Go to the ARTIK 030 programming article for details.

ARTIK 520, 530, 710, and 1020 applications. The EM3587 ZigBee/Thread radio on the ARTIK module works with the Linux main processor on the module as a network co-processor (NCP), connected by a simple serial interface.

The NCP on the modules arrives with its "identity" pre-flashed as a ZigBee command processor. ZigBee application programs then run from the ARTIK main processor itself. The testing described in this article uses zigbee-test and zigbee-cli utility programs, based on the ZigBee API supported by starting zigbee-daemon.

To create and run custom applications of your own, you'll use the API just like the -test and -cli programs do. Network form and join operations are taken care of at your command, and you can easily turn lights on/off or dim them. The ZigBee API complements the ARTIK API, but one does not depend on installation of the other.

Optionally, you can code projects using the Simplicity Studio ZigBee stacks, similar to what you do for the ARTIK 030. In this case, you use your ARTIK 5/7/10 platform to compile the code natively (no compiler license is required), and install a pre-written NCP program. You won't use the ZigBee daemon, the API, or the utility programs.

Prerequisites

This tutorial works with a mix of ARTIK 030, 520, 530, 710, and 1020 boards. You'll need at least two. Once the devices are joined on the network, they will be able to send messages to each other.

  • Obtain any combination of the following boards: ARTIK 030, 520, 530, 710, or 1020.

  • If you intend to develop using the ZigBee software stack, you must register an ARTIK 030 development kit with Silicon Labs. The kit comes with three boards, so one kit is sufficient for testing.

  • For developing software using the stack, install Simplicity Studio 4.0 on your host PC. Have your ARTIK 030 board ready to plug in when you install the software, so that it is automatically recognized and the appropriate drivers installed.

You must register at least one ARTIK 030 kit to allow installation of the ZigBee stacks, even if you only use the stacks for ARTIK 5/7/10 boards.

We recommend that you read the ZigBee fundamentals document in your Simplicity Studio ZigBee installation, usually found at
C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.2\protocol\zigbee
in the documentation folder:
\documentation\UG103-02-AppDevFundamentals-ZigBee.pdf

The time for completing the tutorial portion of this article is about an hour, including the download and installation time for necessary software. The basic steps will be:

  1. Prepare – load needed software and firmware onto the various board types
  2. Create – execute the commands to form and join the ZigBee network.
  3. Command – send ZigBee Cluster Library (ZCL) commands to try them out.

Prepare ARTIK 5/7/10 Boards

Using one or more ARTIK 520, 530, 710, or 1020 kits, you'll build ZigBee device nodes to play with. Any of these board types can talk with any other one, as well as with ARTIK 030 boards prepared as described elsewhere.

You'll run all ZigBee utility and application programs on the ARTIK main processor, which will transfer commands to and return data from the NCP by way of the internal serial port (the same one used for flashing an NCP firmware update).

Two pre-built utility programs provide a shorthand method for testing, avoiding lengthy network form and join sequences to get right to ZCL commands. To create and compile your own application, you'll use ZigBee API calls. Refer to the artik_zigbee_test.c file in the ARTIK IDE section – it's the source for the program that we use here.

Install or update software

To prepare your board, you'll need to do some quick setup and installation checks.

Step 1. Set up repository to install/update software packages for ZigBee

Step 2. If needed, flash-update the NCP to re-establish its "identity" as ZigBee

Step 3. Verify that the internal serial port driver, called zigbee-daemon, is running.


Step 1: Install the latest ZigBee API packages

For Ubuntu:

The main processor firmware image may not include the ZigBee driver and utility programs.

  1. Pull up the ARTIK SDK Installation article, and follow the instructions to install the SDK.

  2. Install the latest ZigBee daemon by running:
    apt remove zigbeed
    apt install zigbeed

For Fedora:

For ARTIK 520, you must use A520-OS-2.0.0 for the built-in daemon. ARTIK 1020 does not include the daemon.

  1. Pull up the ARTIK SDK Installation article, and follow the instructions to:

    1. Set up dnf access to the ARTIK repository and its up-to-date packages

    2. Make sure you enter the last command as indicated:
         dnf makecache --refresh

    3. Install the ARTIK SDK (only if you are using an older build without it).

  2. Update to the latest SDK files (including ZigBee) by entering
       dnf update

  3. Install the latest ZigBee daemon by running:
    dnf remove zigbeed
    dnf install zigbeed

You can verify that you have the updated version (1.2) by entering:
   dnf info libartik-sdk-zigbee

Step 2: Load the ZigBee NCP firmware

The Silicon Labs chip is configured, when the main processor image is loaded, to give it either a ZigBee or a Thread identity. Ubuntu operating system revisions enabled for "on-boarding" will program the NCP with a Thread identity.

If the NCP image is not the latest ZigBee one, you will need to flash back the appropriate ZigBee NCP firmware before proceeding. Refer to NCP Update for details.

Step 3: Check that the ZigBee daemon is running

For all platforms, you'll need to enable the ZigBee daemon that manages the internal serial port traffic. It should start automatically with the latest packages installed.

Check whether it is running.
systemctl status zigbee-daemon

If not, set it to start itself automatically on each reset:
systemctl enable zigbee-daemon
reboot

If zigbee-daemon is not operating in the background, the ZigBee applications and utility programs will not work.

If you are using Home Assistant for ZigBee, you will want to disable zigbee-daemon.

Completion

Your ARTIK 5/7/10 boards are now ready for ZigBee testing.

Continue below if needed to prepare ARTIK 030 boards, or jump to Create ZigBee Network if you are not using any ARTIK 030 devices.

Prepare ARTIK 030 Boards

Using the ARTIK 030 kit, you'll build a pair of ZigBee device nodes to play with. The pre-built examples we'll use are designed to form a network automatically when used with suitably prepared ARTIK 5, 7, and/or 10 boards.

Upload Images

You will first be uploading different images to two ARTIK 030 development boards. If you have already followed the ARTIK 030 Software Getting Started Guide instructions, then you'll have a better understanding of what we present here.

  1. Download zigbee_tutorial_18-05-15.zip; unzip and save the Z3SwitchSoc.s37, Z3LightSoc.s37, and bootloader files onto your PC (shown below saved in the c: root).

  2. Run the Simplicity Studio 4.0 program and go to the Simplicity IDE view.

  3. Connect both boards to your PC using their USB cables, making sure the board switches are set to 'AEM'. The devices appear on the left of the screen with identifier numbers. You'll use these numbers to distinguish between Z3LightSoc and Z3SwitchSoc applications in the following steps.

  4. Upload a main and a bootloader image to each module. In preparation each time:

    1. Left-click to select the device to act on.
    2. Note its number to associate with the application (light or switch).
    3. Right-click and choose Upload application… (see note below if not clickable).
  5. Upload the Z3SwitchSoc.s37 image to one of the ARTIK 030 boards, and Z3LightSoc.s37 to the other.

    1. Click the top folder icon; browse to your downloads and select the Z3SwitchSoc.s37 or Z3LightSoc.s37 file as the main image.
    2. Click the "Bootloader" checkbox.
    3. Click the bottom folder icon; select the pre-built bootloader file as your bootloader image.

    4. Click Erase chip so that the chip will be cleared before upload.
    5. Click OK.

By the way, the next time you do a main image upload, you can skip the "Erase chip" and bootloader parts.

Launch Terminal Console

We'll need terminal emulator consoles for each board to send commands and check status. To save time we can launch both at once.

  1. Open terminal emulator consoles.

    1. Select both devices (Ctrl-left-click on the second one).
    2. Right-click and select Launch Console.

    Once you launch the console, Simplicity automatically connects over the J-Link serial bus. If you need to upload a different image later, hit Disconnect to again make the Upload application… selection clickable.

  2. The console windows default to a tabbed format where you can only see one at a time. Let's rearrange them and pre-select the active terminal tab we'll be using.

    1. Click on and drag one of the tabs to the top, bottom, left, or right of the window; you'll see how it will split the window depending on where you release. A side-by-side view is helpful for our purposes.

    2. Click on each main tab and select the Serial 1 sub-tab on each console window.

  3. With the cursor in the bottom command entry box of the console window, hit the Enter key to get a prompt. If you see it, you're set up now to begin testing.

Create ZigBee Network

You'll need to pick one of your ARTIK 5/7/10 boards to be Coordinator. All other ARTIK 030/5/7/10 boards will be joiners.

ARTIK 030

Plug in both boards and launch their consoles, then exit pre-existing networks.

Start fresh by exiting any pre-existing network. In each console, type
net leave

You may have to repeat this several times until you see EMBER_NETWORK_DOWN and the display stops scrolling.

Z3Switch. The Z3SwitchSoc.s37 image can either join an existing network, or can form its own network and cause the light to bind to it (you don't need to take any action on the light for this case).

Z3Switch Button Function
PB1 (left side) Activate Touchlink (create network, find light, and bind to it)
PB0 (right side) if not joined: JOIN an existing network
if joined: Send ON/OFF Toggle command

To test Touchlink: Just have your A030 Z3Light board ready, then press PB1. Once the binding is complete, you can press PB0 to toggle Z3Light board LED0 on and off.

To test Joining: Set up the ARTIK 5/7/10 board and test as noted.

Z3Light. The Z3LightSoc.s37 image has built-in network join features. These two scenarios both have EMBER_NETWORK_DOWN as the starting state.

Starting point Actions to take on Z3Light
You have activated Touchlink on the A030 Z3Switch (PB1) You won't need to do anything on Z3Light. It reacts to the Touchlink commands from the Z3Switch and will bind with the switch.
You have created an ARTIK 5/7/10 network and are in the Permit Join phase Join the network by pressing RESET.

PB1 and PB0 are not used in either scenario.

If you only have the A030 board kit and no ARTIK 5/7/10 boards, jump ahead to Using the CLI.

ARTIK 5/7/10

Operation is by console using zigbee-test, which is menu-driven and has three menu levels.

MENU 1

Select the functionality
the ARTIK module
will exhibit, then

[0] to go to next menu.
<pre>1: On/Off Switch
2: Level Control Switch   
3: On/Off Light
4: Dimmable Light
5: Light Sensor
6: Occupancy Sensor
7: Temperature Sensor
8: Remote Control
9: IAS Control and Indic Equip
10: Thermostat (Controller)
11: Thermostat (Humid sens)
0: ADD DEVICE DONE </pre>
<pre>










—–» to MENU 2</pre>

MENU 2

Create the network

[7] leave
[1] form + permit join
  »  join each device
then

[8] to begin testing.
<pre>1: Form network
2: Form network (advanced)
3: Join network
4: Join network (advanced)
5: Network find and join
6: Network stop scan
7: Leave network
8: Network permit join
9: Discover device
10: Get discovered device
11: Commissioning operation
12: Start testing </pre>
<pre>« as COORDINATOR

« as END DEVICE




« as COORDINATOR
« as COORDINATOR


—–» to MENU 3</pre>

MENU 3

Test devices in the
network

[1] verify join list
[3] devices blink/beep
<pre>1: Get device information
2: Auto test
3: Identify
4: On/off
5: Level control
6: Illuminance measurement
7: Occupancy Sensor
8: Temperature Sensor
9: Humidity
10: Bind api test
11: Remote Control
12: Thermostat
13: Request reporting test
14: Groups test
15: General api test
16: ZDO test
17: ZCL raw command api test</pre>


Type [0]
to return
to MENU 2

Get up and running quickly

You'll need to have a Switch and a Light. ARTIK 5/7/10 boards for both, set up the coordinator as On/Off Switch, and the other as On/Off Light.

Entries like [1] indicate keyboard numbers only (do not type the brackets).

  1. Set up each ARTIK 5/7/10 board. On the terminal console, type:
    1. systemctl start zigbee-daemon [Enter]
    2. zigbee-test [Enter]
      You may get a preliminary screen; choose [1] [Enter] to Add new device
    3. Choose [1] [Enter] to become an On/Off Switch
      (or [3] [Enter] for On/Off Light on 2nd A5/7/10)
    4. Hit [Enter] by itself, to accept the default endpoint assignment
    5. [0] [Enter] to finish.

    You will now be on Menu 2.

  2. Leave any pre-existing networks.
    • On each ARTIK 5/7/10 console, type [7] [Enter] to Leave Network.
    • On each ARTIK 030 console, type net leave
  3. Establish one of the ARTIK 5/7/10 boards as Coordinator. On its console, type:
    1. [1] [Enter] to form a network
    2. Wait
    3. See FIND FORM SUCCESS? It's done forming and is in the Permit Join phase.
  4. From other devices, join the network within 60s:
    • A030 Z3Light – Press RESET
    • A5/7/10 – Type [3] [Enter] to Join Network
    • Any other ZigBee light device you may have – follow its joining procedure.
  5. On the ARTIK Coordinator:
    • Type [9] [Enter] to Discover devices

That's it! You've set up a network. All devices can communicate now.

  1. Type [12] [Enter] on the Coordinator console to move to Menu 3.
  2. Type [1] [Enter] to see the Node ID ('device id'), EUI (MAC address), and cluster information of each connected device.
  3. Type [4] [Enter] to run an On/Off test on the light. Observe your light device (or your A5/7/10 console) to see the effect of the commands.

Troubleshooting

If you have trouble getting ZigBee networks set up, make sure you have used network leave (or a known hardware equivalent) on all devices to tear down previous networks before starting a fresh one. Pressing a device reset button alone is generally not sufficient.

Before starting the zigbee-test or zigbee-cli program, you can run this command to provide debug output that "follows" events live, as they occur.
   journalctl -f | grep zigbeed &

You'll get messaging to help track down issues.

  • Running the journal is the only way to see output from the zigbee-cli program.

  • You may find that the On/Off test of the zigbee-test program will incorrectly report "there is no endpoint to send on/off command" unless you run the journal.

  • An alternative use of the command:
    journalctl -f -o"cat" &
    strips off the date stamp for cleaner output. You can't pipe this one to grep since it strips off the sort term "zigbeed", so you will also see other system events.

You can instead simply dump the output of journalctl to a file to review it at any time (not following it live).

Next Steps

We need to cover many more topics to get a complete understanding of ZigBee – especially the concepts of binding and commissioning. You may want to first go directly to the article addressing your module type (A5/7/10 gateway vs A030 edge node device) to understand the development process.

Last updated on: