zakaria1193 / mockerbee

A library for emulating pools of ZCL devices for testing your gateways/hubs !

👷 Project is still a draft ! roadmap is still not clearly defined. your comments are welcome

Device Mocker with ZCL API is a powerful library for simulating devices with different ZCL clusters, designed for developers working on IoT devices with Zigbee communication.

Built with modern C++ features, Device Mocker supports both C and C++ APIs and can be easily integrated into your existing project.

Device Mocker is designed to be easy to use, with a simple API that allows you to create a device with just a few lines of code.

Prerequisites

• CMake 3.10 or later
• C++ compiler with C++23 support (Recommended clang-17)

Code quality checks

• libsanitizer
• clang-tidy
• cppcheck
• clang-format

CI Test

Documentation

Concepts

Endpoint & Device & Device Pool

A pool of devices is a collection of devices. A device is a collection of endpoints. each endpoint is a collection of clusters.

A pool has an associated PAN (Personal Area Network) object. Each device in the pool can be in this PAN or not.

A device pool can be enhanced to hold multiple PANs. But it is not considered in the current implementation.

Cluster

ZCL cluster representation object. it mirror a ZCL cluster with all its attributes as if it running on a real device.

Each cluster command is defined by:

• A command descriptor.
• A command executer = a free function that takes a cluster object as a first argument.

The commands are not methods of the cluster object. this is needed because a command can be executed from runtime id resolved from a command ID. using:

class Device
{
  ...

  template <typename... Args>
  zcl::ZclStatus execute_cluster_command(const endpoint_id_t     ep_id,
                                         const zcl::cluster_id_t cluster_id,
                                         const zcl::command_id_t command_id,
                                         bool is_common, Args... args);
}

Create a device pool and communicate with devices

  // Create a device pool with a PAN ID
  device::Pool pool(pan_id);

  // Instantiate a device using a device class
  device::OnOffDevice device(mac_address);

  // Open the pan
  pool.pan.set_permit_joining(true);

  // Make it join the PAN
  device.join_pan(pool.get_pan());

  // Communicate with the device
  device.execute_cluster_command(
      1, zcl::on_off_cluster::cluster_descriptor.id,
      zcl::on_off_cluster::setOffCmdDescriptor.get_id(), false);

Custom clusters and devices

Adding custom cluster

A custom cluster can be added by inheriting from the Cluster class and passing the required attribute descriptors and commands.

namespace my_rocket_cluster_namespace
{
// Cluster descriptor
const cluster_descriptor_t cluster_descriptor{/*id=*/0xF001,
                                              /*is_msp=*/true,
                                              /*description=*/"My rocket cluster"};

const commands_map_t on_off_commands_map = {
    {liftOffCommandDescriptor,
     static_cast<const CommandBase* const>(&liftOffCommand)},
};

// OnOffCluster class
class MyRocketCluster : public Cluster
{
 public:
  RocketCluster()
      : Cluster(
            /*descriptor=*/cluster_descriptor,
            /*attribute_descriptors=*/
            {altitudeAttributeDescriptor, speedAttributeDescriptor,
             coordinatesAttributeDescriptor},
            /*commands_map=*/
  {
  }
};

Add custom device

A device class can be created by inheriting from the Device class and passing the required endpoints with their clusters to the base class constructor.

class OnOffDevice : public Device
{
 public:
  explicit OnOffDevice(const MacAddress& mac_address)
      : Device(mac_address,
               {Endpoint{1, {zcl::on_off_cluster::OnOffCluster()}},
                Endpoint{2, {zcl::my_cluster_namespace::MyCluster()}}
               }){};
};

mockerbee's Issues

autopr workflow

Add proper name

implement Event Class

Event consumer:

As a user

• i should be able to receive events

  • It is my responsability to implemement
  • extern process_event(Event *event)

• The device should report events

  • nwk management events
    • DeviceAnnouncementEven
    • LeaveEvent
    • JoinEvent
  • Cluster specific events (reportings)
    • The device should notify me through periodic events and state changes by calling my “event_consumer_callback”, event should
    • ReportingEvent

Fix Readme

readme should specify that the end goal is not only zigbee devices but also matter devices that use the zcl

Crash if cluster commands list is init to empty map

may affect cluster with empty aattribute list too,

Stop using pointers in the cluster, use refs or smart pointers instead.

Remove namespace zcl

zcl namespace should only be for headers in zcl forlder,
files such as device.hpp should use the global namespace