com_manager.h

Go to the documentation of this file.

/*
MIT LICENSE

Copyright (c) 2014-2021 Inertial Sense, Inc. - http://inertialsense.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions :

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/

#ifndef COM_MANAGER_H
#define COM_MANAGER_H

#ifdef __cplusplus
extern "C" {
#endif
    
#include <stdint.h>
#include "ISComm.h"
#include "linked_list.h"

// allow packet continuation or not. If enabled, an extra 1K buffer is allocated globally for each pHandle instance.
#define ENABLE_PACKET_CONTINUATION 0

// typedef enum
// {
//      /** No pass through */
//      COM_MANAGER_PASS_THROUGH_NONE = 0,
// 
//      /** UBLOX pass through */
//      COM_MANAGER_PASS_THROUGH_UBLOX = UBLOX_START_BYTE1,
// 
//      /** RTCM3 pass through */
//      COM_MANAGER_PASS_THROUGH_RTCM3 = RTCM3_START_BYTE
// } com_manager_pass_through_t;

/* Contains data that determines what messages are being broadcast */
typedef struct
{
        pkt_info_t              pkt;

        /* Broadcast specific data header (i.e. data id, size and offset) */
        p_data_hdr_t            dataHdr;

        /* Broadcast period counter */
        int32_t                 counter;

        /* Millisecond broadcast period intervals.  -1 = send once.  0 = disabled/unused/don't send. */
        int32_t                 period;

        /* Port to broadcast on. */
        int32_t                 pHandle;
} broadcast_msg_t;

/* Contains data to implement ensured packet delivery */
typedef struct
{
        /* Packet struct */
        packet_t                pkt;

        /* Packet contents/body */
        uint8_t                 pktBody[PKT_BUF_SIZE];

        /* Count down counter between retries.  < 0 means disabled. -2 means no more enabled beyond this. */
        int                     counter;

        /* Port packet was sent on */
        int                     pHandle;
} ensured_pkt_t;

typedef struct  
{
        uint32_t readCounter;

        uint32_t rxPktCount;

        uint32_t rxError;

        uint32_t communicationErrorCount;

        uint8_t flags;

} com_manager_status_t;

typedef struct
{
        broadcast_msg_t* broadcastMsg;
        uint32_t broadcastMsgSize;                      // MAX_NUM_BCAST_MSGS * sizeof(broadcast_msg_t)

        ensured_pkt_t* ensuredPackets;          
        uint32_t ensuredPacketsSize;            // cmInstance->maxEnsuredPackets * sizeof(ensured_pkt_t)

} com_manager_init_t;

#define MAX_NUM_BCAST_MSGS 4

// Convenience macros for creating Com Manager buffers
#define COM_MANAGER_BUF_SIZE_BCAST_MSG(max_num_bcast_msgs)              ((max_num_bcast_msgs)*sizeof(broadcast_msg_t))
#define COM_MANAGER_BUF_SIZE_ENSURED_PKTS(max_num_ensured_pkts) ((max_num_ensured_pkts)*sizeof(ensured_pkt_t))

// com manager instance / handle is a void*
typedef void* CMHANDLE;

// com manager callback prototypes
// readFnc read data from the serial port represented by pHandle - return number of bytes read
typedef int(*pfnComManagerRead)(CMHANDLE cmHandle, int pHandle, uint8_t *buffer, int numberOfBytes);

// sendFnc send data to the serial port represented by pHandle - return number of bytes written
typedef int(*pfnComManagerSend)(CMHANDLE cmHandle, int pHandle, unsigned char* buffer, int numberOfBytes);

// txFreeFnc optional, return the number of free bytes in the send buffer for the serial port represented by pHandle
typedef int(*pfnComManagerSendBufferAvailableBytes)(CMHANDLE cmHandle, int pHandle);

// pstRxFnc optional, called after data is sent to the serial port represented by pHandle
typedef void(*pfnComManagerPostRead)(CMHANDLE cmHandle, int pHandle, p_data_t* dataRead);

// pstAckFnc optional, called after an ACK is received by the serial port represented by pHandle
typedef void(*pfnComManagerPostAck)(CMHANDLE cmHandle, int pHandle, p_ack_t* ack, unsigned char packetIdentifier);

// disableBcastFnc optional, mostly for internal use, this can be left as 0 or NULL
typedef void(*pfnComManagerDisableBroadcasts)(CMHANDLE cmHandle, int pHandle);

// Called right before data is to be sent.  Data is not sent if this callback returns 0.
typedef int(*pfnComManagerPreSend)(CMHANDLE cmHandle, int pHandle);

// ASCII message handler function, return 1 if message handled
// typedef int(*pfnComManagerAsciiMessageHandler)(CMHANDLE cmHandle, int pHandle, unsigned char* messageId, unsigned char* line, int lineLength);

// Generic message handler function, return 1 if message handled
typedef int(*pfnComManagerGenMsgHandler)(CMHANDLE cmHandle, int pHandle, const unsigned char* msg, int msgSize);

// pass through handler
// typedef int(*pfnComManagerPassThrough)(CMHANDLE cmHandle, com_manager_pass_through_t passThroughType, int pHandle, const unsigned char* data, int dataLength);

// broadcast message handler
typedef int(*pfnComManagerAsapMsg)(CMHANDLE cmHandle, int pHandle, p_data_get_t* req);

/* Contains callback information for a before and after send for a data structure */
typedef struct
{
        /* Pointer and size of entire data struct (not sub portion that is communicated) */
        bufTxRxPtr_t dataSet;

        /* Callback function pointer, used to prepare data before send */
        pfnComManagerPreSend preTxFnc;

        /* Callback function pointer, used to prepare data after received */
        pfnComManagerPostRead pstRxFnc;

        /* Packet type to use */
        uint8_t pktFlags;
} registered_data_t;

typedef struct
{
        // Comm instances 
        is_comm_instance_t comm;

        // Comm instance data buffer
        uint8_t comm_buffer[PKT_BUF_SIZE];

        // Current status
        com_manager_status_t status;

#if ENABLE_PACKET_CONTINUATION

        // Continuation data for packets
        p_data_t con;

#endif
        
} com_manager_port_t;
        
typedef struct
{
        // reads n bytes into buffer from the source (usually a serial port)
        pfnComManagerRead readCallback;

        // write data to the destination (usually a serial port)
        pfnComManagerSend sendPacketCallback;

        // bytes free in Tx buffer (used to check if packet, keeps us from overflowing the Tx buffer)
        pfnComManagerSendBufferAvailableBytes txFreeCallback;

        // Callback function pointer, used to respond to data input
        pfnComManagerPostRead pstRxFnc;

        // Callback function pointer, used to respond to ack
        pfnComManagerPostAck pstAckFnc;

        // Callback function pointer, used when disabling all broadcast messages
        pfnComManagerDisableBroadcasts disableBcastFnc;

        // Pointer to local data and data specific callback functions
        registered_data_t regData[DID_COUNT];
        
        // Array of port
        com_manager_port_t *ports;
                
        // ensured packets
        ensured_pkt_t* ensuredPackets;

        broadcast_msg_t* broadcastMessages; // MAX_NUM_BCAST_MSGS slots

        int32_t lastEnsuredPacketIndex;

        // Number of communication ports
        int32_t numHandles;

        // max number of packets to ensured delivery at one time.  Adjust based on available memory.
        int32_t maxEnsuredPackets;

        // processing interval
        int32_t stepPeriodMilliseconds;

        // Ensure retry count
        int32_t ensureRetryCount;

        // user defined pointer
        void* userPointer;

        // Broadcast message handler.  Called whenever we get a message broadcast request or message disable command.
        pfnComManagerAsapMsg cmMsgHandlerRmc;

        // Message handler - ASCII
        pfnComManagerGenMsgHandler cmMsgHandlerAscii;

        // Message handler - Ublox
        pfnComManagerGenMsgHandler cmMsgHandlerUblox;

        // Message handler - RTCM3
        pfnComManagerGenMsgHandler cmMsgHandlerRtcm3;

} com_manager_t;


// get the global instance of the com manager - this is only needed if you are working with multiple com managers and need to compare instances
CMHANDLE comManagerGetGlobal(void);

int comManagerInit
(
        int numHandles,
        int maxEnsuredPackets,
        int stepPeriodMilliseconds,
        int retryCount,
        pfnComManagerRead readFnc,
        pfnComManagerSend sendFnc,
        pfnComManagerSendBufferAvailableBytes txFreeFnc,
        pfnComManagerPostRead pstRxFnc,
        pfnComManagerPostAck pstAckFnc,
        pfnComManagerDisableBroadcasts disableBcastFnc,
        com_manager_init_t *buffers,
        com_manager_port_t *cmPorts
);

// Initialize an instance to a com manager that can be passed to instance functions and can later be freed with freeComManagerInstance
// this function may be called multiple times.  Return 0 on success, -1 on failure.
int comManagerInitInstance
(
        CMHANDLE cmHandle,
        int numHandles,
        int maxEnsuredPackets,
        int stepPeriodMilliseconds,
        int retryCount,
        pfnComManagerRead readFnc,
        pfnComManagerSend sendFnc,
        pfnComManagerSendBufferAvailableBytes txFreeFnc,
        pfnComManagerPostRead pstRxFnc,
        pfnComManagerPostAck pstAckFnc,
        pfnComManagerDisableBroadcasts disableBcastFnc,
        com_manager_init_t *buffers,
        com_manager_port_t *cmPorts
);

void comManagerStep(void);
void comManagerStepInstance(CMHANDLE cmInstance_);
void comManagerStepRxInstance(CMHANDLE cmInstance);
void comManagerStepTxInstance(CMHANDLE cmInstance);

void comManagerGetData(int pHandle, uint32_t dataId, int offset, int size, int periodMultiple);
void comManagerGetDataInstance(CMHANDLE cmInstance, int pHandle, uint32_t dataId, int offset, int size, int periodMultiple);

void comManagerGetDataRmc(int pHandle, uint64_t rmcBits, uint32_t rmcOptions);
void comManagerGetDataRmcInstance(CMHANDLE cmInstance, int pHandle, uint64_t rmcBits, uint32_t rmcOptions);

int comManagerDisableData(int pHandle, uint32_t dataId);
int comManagerDisableDataInstance(CMHANDLE cmInstance, int pHandle, uint32_t dataId);

int comManagerSend(int pHandle, uint8_t pktInfo, bufPtr_t* bodyHdr, bufPtr_t* txData, uint8_t pktFlags);
int comManagerSendInstance(CMHANDLE cmInstance, int pHandle, uint8_t pktInfo, bufPtr_t* bodyHdr, bufPtr_t* txData, uint8_t pktFlags);

int comManagerSendData(int pHandle, uint32_t dataId, void* dataPtr, int dataSize, int dataOffset);
int comManagerSendDataInstance(CMHANDLE cmInstance, int pHandle, uint32_t dataId, void* dataPtr, int dataSize, int dataOffset);

int comManagerSendEnsured(int pHandle, uint8_t pktInfo, unsigned char *data, unsigned int dataSize);
int comManagerSendEnsuredInstance(CMHANDLE cmInstance, int pHandle, uint8_t pktInfo, unsigned char *data, unsigned int dataSize);

// INTERNAL FUNCTIONS...
int comManagerSendDataNoAck(int pHandle, uint32_t dataId, void* dataPtr, int dataSize, int dataOffset);
int comManagerSendDataNoAckInstance(CMHANDLE cmInstance, int pHandle, uint32_t dataId, void* dataPtr, int dataSize, int dataOffset);

int comManagerSendRawData(int pHandle, uint32_t dataId, void* dataPtr, int dataSize, int dataOffset);
int comManagerSendRawDataInstance(CMHANDLE cmInstance, int pHandle, uint32_t dataId, void* dataPtr, int dataSize, int dataOffset);

void comManagerDisableBroadcasts(int pHandle);
void comManagerDisableBroadcastsInstance(CMHANDLE cmInstance, int pHandle);

com_manager_status_t* comManagerGetStatus(int pHandle);
com_manager_status_t* comManagerGetStatusInstance(CMHANDLE cmInstance, int pHandle);

bufTxRxPtr_t* comManagerGetRegisteredDataInfo(uint32_t dataId);
bufTxRxPtr_t* comManagerGetRegisteredDataInfoInstance(CMHANDLE cmInstance, uint32_t dataId);

int comManagerGetDataRequest(int pHandle, p_data_get_t* req);
int comManagerGetDataRequestInstance(CMHANDLE cmInstance, int pHandle, p_data_get_t* req);

void comManagerRegister(uint32_t dataId, pfnComManagerPreSend txFnc, pfnComManagerPostRead pstRxFnc, const void* txDataPtr, void* rxDataPtr, int dataSize, uint8_t pktFlags);
void comManagerRegisterInstance(CMHANDLE cmInstance, uint32_t dataId, pfnComManagerPreSend txFnc, pfnComManagerPostRead pstRxFnc, const void* txDataPtr, void* rxDataPtr, int dataSize, uint8_t pktFlags);

void comManagerSetCallbacks(
        pfnComManagerAsapMsg rmcHandler,
        pfnComManagerGenMsgHandler asciiHandler,
        pfnComManagerGenMsgHandler ubloxHandler, 
        pfnComManagerGenMsgHandler rtcm3Handler);
void comManagerSetCallbacksInstance(CMHANDLE cmInstance, 
        pfnComManagerAsapMsg rmcHandler,
        pfnComManagerGenMsgHandler asciiHandler,
        pfnComManagerGenMsgHandler ubloxHandler,
        pfnComManagerGenMsgHandler rtcm3Handler);

void comManagerAssignUserPointer(CMHANDLE cmInstance, void* userPointer);

void* comManagerGetUserPointer(CMHANDLE cmInstance);

int comManagerValidateBaudRate(unsigned int baudRate);

#ifdef __cplusplus
}
#endif

#endif // COM_MANAGER_H