Homec4science
Diffusion sbcp-uc (flash_stripable) Browse

sbcp-uc/include/sbcp.h
26fad3beac65flash_stripable

Last Change
Raw File

sbcp.h
View Options

#ifndef SBCP_UC_SBCP_H_
#define SBCP_UC_SBCP_H_
#include "common.h"
#include "uart.h"
#include "register.h"
#include "instruction.h"
#include "gpio.h"
/**
* \defgroup sbcp_m SBCP module
*
* \brief The main sbcp module.
*
* The main sbcp module is first initialized with sbcp_init(). Initialization is
* performed by :
* - providing lot of settinsg through sbcp_settings structure.
* - user defined callbacks \ref sbcp_init_device_registers_fptr and
* \ref sbcp_init_device_instructions_fptr that are used to define the device
* \ref sbcp_register_m and device \ref sbcp_instruction_m
*
* Then you should inside the main loop of your program call
* sbcp_process().
*
*/
/**
* \mainpage
*
* libsbcp-uc is a dsPIC33 library to develop simply and quickly SBCP interface.
* SBCP stands for Simple Byte Communication Protocol. It is a powerful and
* flexible polling serial protocol over UART (see \ref what_is_sbcp).
*
* If you are interested to use SBCP in your project, please first see
* \ref hardware_requirements and take a look at our \ref how_to. You may even go
* deeper and browse \ref sbcp_m.
*/
/**
* \page what_is_sbcp What is SBCP ?
*
*
*/
/**
* \page how_to How To use in external project
*
* MPLAB X setup :
* -# Create a new config for your project in libSBCP-uc.X project, with the
* right uC.
* -# TODO : how to link to another project.
* -# optionally change the preprocessor macro SBCP_REGISTER_TABLE_SIZE,
* SBCP_INST_TABLE_SIZE, SBCP_LOW_LATENCY_IN_SIZE and
* SBCP_LOW_LATENCY_OUT_SIZE to taylor your need.
* -# create a sbcp_init_registers_fptr and sbcp_init_instructions_fptr fucntion
* to initialize registers and instructions.
* - For registers, create callback, and don't forget to specify which one are
* low latency in/out.
* - For instruction create as many function that you need
* -# call sbcp_init() in your initialization function
* -# call sbcp_process() in your main loop.
*
*
*/
/**
* \page hardware_requirements
*
* libsbcp-uc needs to take some feature on the hardware of the dsPIC33.
*
* it will need :
* - An UART, you can configure wich one to use (unsimplemented yet, please use UART_1)
* - 2 DMA channel, that will always be channel 0 and 1
* - One timer that is timer 4.
* - One or two GPIO PIN to enable/disable RS 485 communication
*/
#ifdef SBCP_PROVIDE_MAIN
/**
* Settings for the SBCP module. user are intended to modify thsi structure
* directly. You can use sbcp_init_settings() to put some good default inside
* this structure.
*
* \ingroup sbcp_m
*/
typedef struct sbcp_settings {
/**
* the baudrate of the bus UART.
*/
unsigned long baudrate;
/**
* Clock frequency of the system in Herz
*/
unsigned long clock_frequency;
/**
* uart_device to use for SBCP communication, see \ref hardware_requirements.
* \warning Unimplemented yet, always set this to UART_1
*/
uart_device uart;
/**
* A gpio that is used to enable the driving of the RS485 line. when set, the
* uc should drive the line.
*/
gpio send_enable;
/**
* A gpio that is used to disable the receiving of the RS485 line. When set,
* the uc should not listen the line.
*/
gpio receive_disable;
/**
* Frequency in Herz where a timeout will be issued.
*/
unsigned int timeout_frequency;
/**
* sbcp_class of the device
*/
sbcp_class klass;
/**
* sbcp_id of the device
*/
sbcp_id id;
/**
* sbcp_fw_version of the device
*/
sbcp_fw_version version;
/**
* User provided function to set up all the device specific \ref sbcp_register_m
*/
sbcp_init_device_registers_fptr init_register;
/**
* User provided function to set up all the device specific \ref sbcp_instruction_m
*/
sbcp_init_device_instructions_fptr init_instruction;
} sbcp_settings;
/**
* Inits a sbcp_settings with good-sense provided values.
* \ingroup sbcp_m
* @param s the strucure to initialize
* @param klass the sbcp_class of the device
* @param id the sbcp_id of the device
* @param version the current firmware version
* @param send_enable the gpio to enable the sending
* @param receive_disable the gpio to disable the reception
*/
void sbcp_init_settings(sbcp_settings * s ,
sbcp_class klass, sbcp_id id,
sbcp_fw_version version,
gpio send_enable,
gpio receive_disable);
/**
* Inits the sbcp module
* \ingroup sbcp_m
* @param s the sbcp_settings to use
*/
void sbcp_init(sbcp_settings * s);
/**
* Process the main loop of SBCP communication. User should call this method
* in the main loop of the program.
* \ingroup sbcp_m
*/
void sbcp_process();
/**
* \internal
*/
void sbcp_mark_tx_buffer_occupied();
/**
* Appends a new register that will be written by a low latency
* instruction.
* \ingroup sbcp_register_m
* @param address the address of the sbcp_register
*/
void sbcp_append_low_latency_in_register(sbcp_reg_address address);
/**
* Appends a new register that will be read and send back during a low latency
* instruction
* \ingroup sbcp_register_m
* @param address
*/
void sbcp_append_low_latency_out_register(sbcp_reg_address address);
/**
* Marks that new data that is read by a low latency instruction is available.
* You have to call this to inform sbcp_process() to prepare that data for the
* next low latency instruction.
* \ingroup sbcp_m
*/
void sbcp_mark_new_low_latency_data_available();
#endif //SBCP_PROVIDE_MAIN
#endif //SBCP_UC_SBCP_H_
c4science · Help