message.h

Go to the documentation of this file.

/******************************************************************************
 * Copyright 2020 ETC Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 ******************************************************************************
 * This file is a part of RDM. For more information, go to:
 * https://github.com/ETCLabs/RDM
 *****************************************************************************/
 
#ifndef RDM_MESSAGE_H_
#define RDM_MESSAGE_H_
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "etcpal/error.h"
#include "rdm/uid.h"
#include "rdm/defs.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define RDM_MAX_BYTES 257
 
#define RDM_MIN_BYTES 26
 
#define RDM_MAX_PDL 231
 
#define RDM_HEADER_SIZE 24
 
#define RDM_OFFSET_STARTCODE 0
#define RDM_OFFSET_SUBSTART 1
#define RDM_OFFSET_LENGTH 2
#define RDM_OFFSET_DEST_MANUFACTURER 3
#define RDM_OFFSET_DEST_DEVICE 5
#define RDM_OFFSET_SRC_MANUFACTURER 9
#define RDM_OFFSET_SRC_DEVICE 11
#define RDM_OFFSET_TRANSACTION 15
#define RDM_OFFSET_PORTID_RESPTYPE 16
#define RDM_OFFSET_MSGCOUNT 17
#define RDM_OFFSET_SUBDEVICE 18
#define RDM_OFFSET_COMMAND_CLASS 20
#define RDM_OFFSET_PARAM_ID 21
#define RDM_OFFSET_PARAM_DATA_LEN 23
#define RDM_OFFSET_PARAM_DATA 24
typedef enum
{
  kRdmCCDiscoveryCommand = E120_DISCOVERY_COMMAND,
  kRdmCCDiscoveryCommandResponse = E120_DISCOVERY_COMMAND_RESPONSE,
  kRdmCCGetCommand = E120_GET_COMMAND,
  kRdmCCGetCommandResponse = E120_GET_COMMAND_RESPONSE,
  kRdmCCSetCommand = E120_SET_COMMAND,
  kRdmCCSetCommandResponse = E120_SET_COMMAND_RESPONSE
  // No "num command classes" placeholder here, because the command class values are not contiguous
} rdm_command_class_t;
 
typedef enum
{
  kRdmResponseTypeAck = E120_RESPONSE_TYPE_ACK,
  kRdmResponseTypeAckTimer = E120_RESPONSE_TYPE_ACK_TIMER,
  kRdmResponseTypeNackReason = E120_RESPONSE_TYPE_NACK_REASON,
  kRdmResponseTypeAckOverflow = E120_RESPONSE_TYPE_ACK_OVERFLOW,
} rdm_response_type_t;
 
typedef enum
{
  kRdmNRUnknownPid = E120_NR_UNKNOWN_PID,
  kRdmNRFormatError = E120_NR_FORMAT_ERROR,
  kRdmNRHardwareFault = E120_NR_HARDWARE_FAULT,
  // TODO: Change "line master" to different terminology once it's changed in the standard.
  kRdmNRProxyReject = E120_NR_PROXY_REJECT,
  kRdmNRWriteProtect = E120_NR_WRITE_PROTECT,
  kRdmNRUnsupportedCommandClass = E120_NR_UNSUPPORTED_COMMAND_CLASS,
  kRdmNRDataOutOfRange = E120_NR_DATA_OUT_OF_RANGE,
  kRdmNRBufferFull = E120_NR_BUFFER_FULL,
  kRdmNRPacketSizeUnsupported = E120_NR_PACKET_SIZE_UNSUPPORTED,
  kRdmNRSubDeviceOutOfRange = E120_NR_SUB_DEVICE_OUT_OF_RANGE,
  kRdmNRProxyBufferFull = E120_NR_PROXY_BUFFER_FULL,
  kRdmNRActionNotSupported = E137_2_NR_ACTION_NOT_SUPPORTED,
  kRdmNREndpointNumberInvalid = E137_7_NR_ENDPOINT_NUMBER_INVALID,
  kRdmNRInvalidEndpointMode = E137_7_NR_INVALID_ENDPOINT_MODE,
  kRdmNRUnknownUid = E137_7_NR_UNKNOWN_UID,
  kRdmNRUnknownScope = E133_NR_UNKNOWN_SCOPE,
  kRdmNRInvalidStaticConfigType = E133_NR_INVALID_STATIC_CONFIG_TYPE,
  kRdmNRInvalidIpv4Address = E133_NR_INVALID_IPV4_ADDRESS,
  kRdmNRInvalidIpv6Address = E133_NR_INVALID_IPV6_ADDRESS,
  kRdmNRInvalidPort = E133_NR_INVALID_PORT,
 
  /****************************************************************************
   * UPDATE THE DEFINE BELOW IF ADDING ENUM VALUES
   ***************************************************************************/
} rdm_nack_reason_t;
 
#define RDM_NUM_STANDARD_NR_CODES 20
 
typedef struct RdmBuffer
{
  uint8_t data[RDM_MAX_BYTES]; 
  size_t  data_len;            
} RdmBuffer;
 
#define RDM_GET_COMMAND_CLASS(rdmbufptr) ((rdmbufptr)->data[RDM_OFFSET_COMMAND_CLASS])
 
#define RDM_GET_TRANSACTION_NUM(rdmbufptr) ((rdmbufptr)->data[RDM_OFFSET_TRANSACTION])
 
typedef struct RdmCommandHeader
{
  RdmUid source_uid;
  RdmUid dest_uid;
  uint8_t transaction_num;
  uint8_t port_id;
  uint16_t subdevice;
  rdm_command_class_t command_class;
  uint16_t param_id;
} RdmCommandHeader;
 
typedef struct RdmResponseHeader
{
  RdmUid source_uid;
  RdmUid dest_uid;
  uint8_t transaction_num;
  rdm_response_type_t resp_type;
  uint8_t msg_count;
  uint16_t subdevice;
  rdm_command_class_t command_class;
  uint16_t param_id;
} RdmResponseHeader;
 
#define RDM_PACKED_SIZE(data_len) (RDM_HEADER_SIZE + (data_len) + 2u)
 
void rdm_pack_checksum(uint8_t* buffer, size_t data_len_without_checksum);
bool rdm_validate_msg(const RdmBuffer* buffer);
 
bool rdm_command_header_is_valid(const RdmCommandHeader* cmd_header);
bool rdm_response_header_is_valid(const RdmResponseHeader* resp_header);
 
etcpal_error_t rdm_pack_command(const RdmCommandHeader* cmd_header,
                                const uint8_t*          cmd_data,
                                uint8_t                 cmd_data_len,
                                RdmBuffer*              buffer);
etcpal_error_t rdm_pack_command_with_custom_buf(const RdmCommandHeader* cmd_header,
                                                const uint8_t*          cmd_data,
                                                uint8_t                 cmd_data_len,
                                                uint8_t*                buf,
                                                size_t                  buf_len);
 
etcpal_error_t rdm_pack_response(const RdmCommandHeader* cmd_header,
                                 uint8_t                 msg_count,
                                 const uint8_t*          response_data,
                                 uint8_t                 response_data_len,
                                 RdmBuffer*              buffer);
etcpal_error_t rdm_pack_overflow_response(const RdmCommandHeader* cmd_header,
                                          const uint8_t*          response_data,
                                          uint8_t                 response_data_len,
                                          RdmBuffer*              buffer);
etcpal_error_t rdm_pack_nack_response(const RdmCommandHeader* cmd_header,
                                      uint8_t                 msg_count,
                                      rdm_nack_reason_t       nack_reason,
                                      RdmBuffer*              buffer);
etcpal_error_t rdm_pack_timer_response(const RdmCommandHeader* cmd_header,
                                       uint8_t                 msg_count,
                                       unsigned int            delay_time_ms,
                                       RdmBuffer*              buffer);
etcpal_error_t rdm_pack_dub_response(const RdmUid* responder_uid, RdmBuffer* buffer);
 
size_t         rdm_get_num_responses_needed(uint16_t param_id, size_t response_data_len);
etcpal_error_t rdm_pack_full_response(const RdmCommandHeader* cmd_header,
                                      const uint8_t*          response_data,
                                      size_t                  response_data_len,
                                      RdmBuffer*              buffers,
                                      size_t                  num_buffers);
 
etcpal_error_t rdm_append_parameter_data(RdmBuffer*     buffer,
                                         const uint8_t* additional_data,
                                         uint8_t        additional_data_len);
 
etcpal_error_t rdm_unpack_command(const RdmBuffer*  buffer,
                                  RdmCommandHeader* cmd_header,
                                  const uint8_t**   param_data,
                                  uint8_t*          param_data_len);
etcpal_error_t rdm_unpack_response(const RdmBuffer*   buffer,
                                   RdmResponseHeader* resp_header,
                                   const uint8_t**    param_data,
                                   uint8_t*           param_data_len);
etcpal_error_t rdm_unpack_dub_response(const RdmBuffer* buffer, RdmUid* responder_uid);
 
unsigned int      rdm_get_ack_timer_delay(const uint8_t* param_data);
rdm_nack_reason_t rdm_get_nack_reason_code(const uint8_t* param_data);
 
const char* rdm_command_class_to_string(rdm_command_class_t command_class);
const char* rdm_response_type_to_string(rdm_response_type_t resp_type);
const char* rdm_nack_reason_to_string(rdm_nack_reason_t reason_code);
 
#ifdef __cplusplus
}
#endif
 
#endif /* RDM_MESSAGE_H_ */