smarthomatic

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Introduction ======

The packet and message format is defined in an XML file. Header files with access functions are generated from it and stored under the "src_common" directory. If you write or change a device firmware, use solely these functions to create and interpret the packet data easily.

Please read about the [[http://www.smarthomatic.org/basics/communication_protocol.html|concept]] first before you continue.

====== Add Includes ======

Decide which MessageGroup (device interface) you want to support. We assume using the "tempsensor" MessageGroup. Include the according header file with

''#include "../src_common/msggrp_tempsensor.h"''

====== Creating a Packet to Send ======

We assume you want to create a packet of the MessageType "Status" for the message "TempHumBriStatus" of message group "tempsensor". (Look into the [[http://www.smarthomatic.org/basics/message_catalog.html|Message Catalog]] for all available MessageTypes and messages.)

===== Init header and header extension =====

''pkg_header_init_//tempsensor//_//temphumbristatus//_//status//();''

This function:

  * clears the packet byte array
  * sets the MessageType in the header
  * sets the MessageGroupID and MessageID in the header extension
  * remembers the header length in a variable used later on

===== Set header data =====

Set all **additional** header fields not initialized with the before mentioned init function (without the CRC32 value, look into the [[http://www.smarthomatic.org/basics/communication_protocol.html#basic_packet_layout|basic packet layout]] for details!).

''pkg_header_set_senderid(my_device_id);''\\
''pkg_header_set_packetcounter(my_packetcounter);''

===== Set header extension data =====

If the header extension for the message type you want to use contains **additional** fields (not initialized with the before mentioned init function), set all of them (look into the [[http://www.smarthomatic.org/basics/communication_protocol.html#basic_packet_layout|basic packet layout]] for details!).

There are two ways to write these values to the header extension:

==== 1) Use the common access function ====

For all fields of the header extensions that appear in more than one message type (which should be all of them...), you can use the common access function defined in the packet_headerext_common.h file. This function automatically calls the appropriate function of the existing message type, using the correct offsets. This makes the implementation in your code easier.

Use the function like this:

''pkg_headerext_**common**_set_ackpacketcounter(received_packetcounter);''

:!: If you use this function on a packet with a message type which has no such field in the header extension, you write nothing to it and nothing bad happens. But be sure to write only fields which exist in the received packet!

==== 2) Use a specific function for your message type ====

As an alternative, or if the value is only in one of the header extensions, you can directly use the function of the appropriate message type like this:

''pkg_headerext_**ack**_set_ackpacketcounter(received_packetcounter);''

This is also recommended if only requests of one message type are supported in a device. Using the function makes it clear in the source code that a specific type of message is created.
===== Set message data =====

If the MessageType you want to use contains message data, set the values by using the functions defined in the header file like:

''msg_tempsensor_temphumbristatus_set_temperature(my_temp);''\\
''msg_tempsensor_temphumbristatus_set_humidity(my_hum);''\\
''msg_tempsensor_temphumbristatus_set_brightness(my_bri);''

These functions are independent on the message type.

:!: Make sure you don't call it with a message type that does not contain message data!
===== Calculate CRC32 =====

Use the following function to calculate the CRC32 of the packet data and to write it to the header. This function automatically uses the correct length of your packet, which is a multiple of 16 bytes (= one AES block).

''pkg_header_calc_crc32();''

===== Send packet =====

You can now send the packet or print it out for debugging.

====== Interpret a Received Packet ======

===== CRC Check =====

After decoding the packet using the AES algorithm, the CRC checksum in the header has to be checked:

''uint8_t len = rfm12_rx_len();\\
if (pkg_header_check_crc32(len))\\
{\\
  /* OK, process the packet */\\
}''


Use the packet length (multiple of 16) you get from the rfm12 function. If it is ok, the packet content can assumed to be valid.

===== Adjust header offset =====

Before accessing packet data, call the function to adjust the (internal) header offset depending on the MessageType. The data can't be decoded correctly otherwise.

''pkg_header_adjust_offset();''
===== Read header =====

Read the SenderID, PacketCounter and MessageType from the packet:

''uint32_t senderid = pkg_header_get_senderid();\\
uint32_t packetcounter = pkg_header_get_packetcounter();\\
MessageTypeEnum messagetype = pkg_header_get_messagetype();''
===== Read header extension =====

As with writing data to a packet (see above), there are also two ways to read values from the header extension:

==== 1) Use the common access function ====

For all fields of the header extensions that appear in more than one message type (which should be all of them...), you can use the common access function defined in the packet_headerext_common.h file. This function automatically calls the appropriate function of the existing message type, using the correct offsets. This makes the implementation in your code easier.

Use the function like this:

''uint32_t messagegroupid = pkg_headerext_**common**_get_messagegroupid();\\
uint32_t messageid = pkg_headerext_**common**_get_messageid();''

:!: If you use this function on a packet with a message type which has no such field in the header extension, you get a value "0". Be sure to read only fields which exist in the received packet!

==== 2) Use a specific function for your message type ====

As an alternative, or if the value is only in one of the header extensions, you can directly use the function of the appropriate message type like this:

''uint32_t messagegroupid = pkg_headerext_**get**_get_messagegroupid();\\
uint32_t messageid = pkg_headerext_**get**_get_messageid();''

This is recommended if only requests of one message type are supported in a device. Using the function makes it clear in the source code that e.g. a "Get" packet is assumed to be processed.
===== Read message data =====

If the received packet contains message data, access it by using the functions defined for the message group:

''bool on = msg_powerswitch_switchstate_get_on();''