Zstack linux gateway API

Hi Nicolas,

The sources of the demo application are a good place to look at how an actual packet may be sent across the wire. 

Do you have access to the Z-Stack Linux Gateway Developer's Guide ? It should be available with the source-release of the Linux Gateway. It walks through the demo application and talks about all the major building blocks of the Gateway Application. 

Here are some excerpts from that documentation that may answer your question:

Note: All files referred are sources of the Demo Application that are made available with the Linux Gateway installation.

Section 6.1.1 (that talks about the Protobuf Encoded packet that needs to be sent to the servers):

For instance, say your application wants to send a command to the Gateway to determine the status of the network. There’s a Network Manager API for it called NWK_ZIGBEE_NWK_INFO_REQ (Z-Stack Linux Gateway API document, Section 8.2.2). Your application would then construct a message to send to the Network Manager server as shown here:

<GATEWAY SAMPLE APP>/engines/network_info_engine.c:
129   void nwk_send_info_request(void)
130    {
131   pkt_buf_t * pkt = NULL;
132   uint8_t len = 0;

133   NwkZigbeeNwkInfoReq msg = NWK_ZIGBEE_NWK_INFO_REQ__INIT;
134
135   UI_PRINT_LOG("nwk_send_info_request: Sending NWK_INFO_REQ__INIT");
136

137   len = nwk_zigbee_nwk_info_req__get_packed_size(&msg);
138   pkt = malloc(sizeof(pkt_buf_hdr_t) + len);
139
140   if (pkt)
141   {
142   pkt->header.len = len;

143   pkt->header.subsystem = Z_STACK_NWK_MGR_SYS_ID_T__RPC_SYS_PB_NWK_MGR;
144   pkt->header.cmd_id = NWK_MGR_CMD_ID_T__NWK_ZIGBEE_NWK_INFO_REQ;
145

146   nwk_zigbee_nwk_info_req__pack(&msg, pkt->packed_protobuf_packet);

147

148   if (si_send_packet(pkt, (confirmation_processing_cb_t)&nwk_process_info_cnf, NULL) != 0)
149

The yellow lines highlighted above show the three protobuf APIs that are called to initialize a message object (<>__INIT), determine its length (<>__get_packed_size), and then pack or encode it (<>_req__pack) into the actual message that is then sent across the socket interface

The blue lines highlighted above show memory being allocated for the encoded message and this 4-byte header, and then the fields of the header being populated before the packet is sent to the socket interface function:

The structure of the packet that is sent across to the server is defined in the following file:

<GATEWAY SAMPLE APP>/framework/types.h:
96   typedef struct
97   {
98     uint16_t len;
99     uint8_t subsystem;
100   uint8_t cmd_id;
101   } pkt_buf_hdr_t;
102
103   typedef struct
104   {
105     pkt_buf_hdr_t header;
106     uint8_t packed_protobuf_packet[];
107   } pkt_buf_t;

It would help to browse through the sources of the Demo Application to see how packets are being sent/received etc. 

Let us know if you have any other questions.

Thanks,

GD

I gave a look to the source code and found some piece of information.

The packet to send via TCP connection on port 2533 (default) seems to be built from 2 fields : HEADER and protobuf packed PACKET

HEADER building is pretty clear : length of the protobuf packed packet, subsystem (18 for network manager in our case right ?) and the command ID (from what I read in the _NwkMgrCmdIdT enum, it seems that our command id is 10).

the protobuf packed PACKET seems to be built from BASE and CMD ID fields.

If CMD ID field seems to be the same ID as the header one, the BASE field looks to be more complicated to build.

BASE field is a ProtobufCMessage type, which is a structure made of

const ProtobufCMessageDescriptor *descriptor;
unsigned n_unknown_fields;
ProtobufCMessageUnknownField *unknown_fields;

Building this BASE field looks not so easy as it refers some intricated #define and structures...

A lot of BASE subfields seems to be descriptors for the protobuf serialization (I guess, I'm not sure).

In my particular case, I would like to build a c# application to communicate with the API in order to manage zigbee network.

Does it change anything to the approach I should use ?

The protobuf serialization, in my c# programm, will be done using protobuf-net lib, by using protocontract classes.

Should I sitck on trying to fully understand how the BASE subfields are built ?

Thanks for your support,

Nicolas

Looks like the Z-Stack Linux Gateway Developer's Guide is not available yet for public consumption. However I can continue to provide help via this forum as you need it.

Thanks,

GD

Hi Gunjan,
Thanks for the reply.

As per my knowledge for performing any action ( let us say on/off ) the two devices need to be potentially binded ( consider gateway device as coordinator and any remote device which has SampleLight application running on it as router ).
When I send any action command from coordinator to any router, the source endpoint with endpoint id 2 (Gateway endpoint) is selected by default.
I did not find any API/command/function where I can define this source endpoint while sending packet.

My questions are-
1) From where can I know the supported clusters by this Gateway endpoint?
2) Can I change this endpoint (from 2 to any other user defined) somehow while sending packet?

Thank you once again and any help regarding this is much appreciated.

Regards,
Edge G.

Hello,

Once you add a light device in the network, the local device (Gateway, acting as coordinator) can always send an ON/OFF command to it, and this will happen via the Gateway Endpoint (configured to be #2). 

If you have another switch added to the network (such as, say the Sample Switch), then in order for this switch to be able to send any command to a light in the network, you will need to bind the two per instructions in the Z-Stack Linux Gateway User's Guide. Once binding is done, turning that switch on and off, should turn the Sample Light on and off.

Here is the list of clusters supported by the Gateway endpoint (endpoint #2):

Endpoint 2 Simple Descriptor is defined as follows:
Profile: HA
Device ID: Combined Interface
Device Ver: 0
Flags: 0
Input Clusters:
Basic
Identify
On Off
IAS ACE
Output Clusters:
On Off
Alarms
Poll Control

More endpoints can be added to the Gateway device via a configuration file with the extension .tlg. See section 5.3 Gateway Manager Server in Z-Stack Linux Gateway User's Guide for details. 

Hi Gunjan,

Thanks for the reply.

The thing is I want to add support for the Window Covering action feature in the present Gateway Subsystem application ( provided with the Z-Stack_Linux_Gateway-1.0.1).

I found that DEV_WINDOW_COVERING_ACTION_REQ API command is already there for adding the Window Covering action.

I was not sure whether the related ZCL_CLUSTER_ID_CLOSURES_WINDOW_COVERING cluster is defined for the Gateway endpoint (endpoint #2) so I had asked you the 1) question in my previous reply.

I have added the above action in the present Gateway Subsystem application and I am able to send the packets for the Up/Open, Down/Close commands for the DEV_WINDOW_COVERING_ACTION_REQ. (I checked this using UBIQUA)

As you have mentioned in the above reply I did not find the ZCL_CLUSTER_ID_CLOSURES_WINDOW_COVERING cluster in the output cluster list of the Gateway endpoint (endpoint #2).

How is it still working?

Regards,

Edge G.

hi, Gunjan

           I am a developer from China , and now my team want to use your gateway to do some project. We already have the beaglebone black board ,and we have successfully run the gateway 1.0.1. But we want to do some modifications about your gateway application to make that adapt to our requirement, and I have also read the API document in the gateway docs packet. I also find that doc is not very helpful.

           After reading what U said above , your answer seems to be very helpful to me. However, there are still lot of questions I need to figure out. Just hope U can give me some advice. 

1. the API is just word or marco ?  there is no real funcs that named after the API such as DEV_SET_COLOR_REQ. Is that right?

2. According to the application source code ,I think that To develop with the API means just use the ***__INIT    ***__get_packed_size()   __pack()  and pkt ->header needs to be specificate. Is that almost enough to realize the functions that the gateway supports? 

3.If all above is right ,is it true that we can only realize the function that API supports instead of creating some new functions. For example, there is no pressure sensor functions in this gateway, so there is no way to make the gateway to support  this device until TI to update the gateway server?    

          Actually, what really bothered me til now is that I do not know the API' s real role in the gateway and how much flexibility for users to develop. In my opinion , after reading the demo application code , I think that is really integrated with all  the API  in the demo and there is no need for us to do some real development with this gateway ---just changing or deleting some code in the demo code is all the work.

Looking forward to ur answer,

best regards!

Charles Lee