[ag-automation] LDI-Interface
Thomas Rothfuss
tb10rts at web.de
Fri Jul 6 08:26:54 CEST 2007
Robert Schwebel wrote:
> On Thu, Jul 05, 2007 at 04:18:20PM +0200, Herbert.Graf at homag.de wrote:
>
>>2. acyclic interface
>>All other parameters for the drives (e.g. software endposition, jerk,
..) can
>>be read or written by the FAPIA-Interface
(Fieldbus-APplication-Interface-A
>>cyclic).
>>The FAPIA-interface consists of:
>>
>> * ReadRequest: to get the value of the parameter
>> * WriteRequest: to write the value of the parameter
>> * InfoRequest: to get the properties of the parameter
>>
>>FAPIA lib is available from HOMAG.
>
>
> Please post it somewhere, to make it possible to start review. The
> important thing wrt. design is the abstraction and configuration/mapping
> concept here as well.
>
A caller has to do following steps:
1. Set the callback functions for the kind of responses needed:
fapia_set_callback_for_parameter_read_response_callback (
fapia_parameter_read_response_callback)
fapia_set_callback_for_parameter_write_response_callback (
fapia_parameter_write_response_callback)
fapia_set_callback_for_parameter_info_response_callback (
fapia_parameter_info_response_callback)
2. Call the init function:
fapia_init (argc, argv, "CNC")
Runtime parameter could be "-FAPIADebugLevel <debug level>"
3. Do the communication
fapia_parameter_read_request (...)
The FAPIA-Lib has own threads. Within such a thread the callback set
by the application (in point 1 it's
fapia_parameter_read_response_callback)is called. Within this
function the application can handle the response.
Write and Info requests are similar.
4. End the communication
Just call
fapia_deinit ();
*******************************************************************************
A callee has to do following steps:
1. Set the callback functions for the kind of requests which are expected:
fapia_set_callback_for_parameter_read_request_callback (
fapia_parameter_read_request_callback)
fapia_set_callback_for_parameter_write_request_callback (
fapia_parameter_write_request_callback)
fapia_set_callback_for_parameter_info_request_callback (
fapia_parameter_info_request_callback)
2. Call the init function:
fapia_init (argc, argv, "CAN1")
Runtime parameter could be "-FAPIADebugLevel <debug level>"
3. Do the communication
When a caller sends a request the appropriate callback function
which was set by the callee is called (e.g.
fapia_parameter_read_request_callback (...)).
In this example the CAN1-Process may get a read request. It then
reads the values from the CAN-bus (this may happen in the
callback-function) and sends the result to the caller by function
fapia_parameter_read_response (...)
Write and Info are similar.
4. End the communication
Just call
fapia_deinit ();
*******************************************************************************
Here is the Interface-Headerfile:
/* -*- C -*- */
//=============================================================================
/**
* @file FAPIA.h
*
* $Id$
*
* @author Thomas Rothfuss <thomas.rothfuss at homag.de>
*/
//=============================================================================
#ifndef _FAPI_ACYCLIC_H_
#define _FAPI_ACYCLIC_H_
#ifdef __cplusplus
extern "C" {
#endif
//=============================================================================
/**
* Structures
*/
//=============================================================================
/**
* @struct FAPIAParameter
*
* @brief This structure is used to identify a Parameter.
*
*/
typedef struct
{
/// Name of the parameter. E.g. "<parameter_number>[;<subindex>]".
char * parameter_name;
} FAPIAParameter;
/**
* @enum FAPIADataType
*
* @brief Enumeration for datatypes.
*
*/
typedef enum
{
FAPIA_DATA_TYPE_UNS08 = 1,
FAPIA_DATA_TYPE_SGN08 = 2,
FAPIA_DATA_TYPE_UNS16 = 3,
FAPIA_DATA_TYPE_SGN16 = 4,
FAPIA_DATA_TYPE_UNS32 = 5,
FAPIA_DATA_TYPE_SGN32 = 6,
FAPIA_DATA_TYPE_STRING = 7,
FAPIA_DATA_TYPE_REAL32 = 8,
FAPIA_DATA_TYPE_REAL64 = 9
} FAPIADataType;
/**
* @struct FAPIAValue
*
* @brief This structure is used to transmit the value for a parameter.
*
*/
typedef struct
{
/// Datatype of the value.
FAPIADataType data_type;
/// Length in bytes of the value.
unsigned long data_length;
/// Pointer to the value. Dependend on the data_type it must be
casted.
void* data_value;
} FAPIAValue;
/**
* @enum FAPIAErrorCode
*
* @brief Possible error codes.
*
*/
typedef enum
{
FAPIA_ERROR_OK = 0,
FAPIA_ERROR_COMMUNICATION = -1,
FAPIA_ERROR_DESTINATION_NOT_ONLINE = -2,
FAPIA_ERROR_OBJECT_NOT_FOUND = -3,
FAPIA_ERROR_PARAMETER_NOT_FOUND = -4,
FAPIA_ERROR_CONFIG_PARSE_ERROR = -5,
FAPIA_ERROR_CONFIG_HAS_WRONG_FORMAT = -6,
FAPIA_ERROR_SYNCHRONIZE_COULD_NOT_BE_INITIALIZED = -7,
FAPIA_ERROR_SHARED_MEMORY_ERROR = -8
} FAPIAErrorCode;
/**
* @struct FAPIAError
*
* @brief This structure holds the error information.
*
*/
typedef struct
{
/// Error code of the error.
FAPIAErrorCode error_code;
/// Reason as a string.
char * reason;
} FAPIAError;
/**
* @enum FAPIACommunicationPriority
*
* @brief Priority of the Message. Default should be
* FAPIA_COMMUNICATION_PRIORITY_NORMAL.
*
*/
typedef enum
{
FAPIA_COMMUNICATION_PRIORITY_LOWEST = 1,
FAPIA_COMMUNICATION_PRIORITY_LOW = 2,
FAPIA_COMMUNICATION_PRIORITY_NORMAL = 3,
FAPIA_COMMUNICATION_PRIORITY_HIGH = 4,
FAPIA_COMMUNICATION_PRIORITY_HIGHEST = 5
} FAPIACommunicationPriority;
/**
* @struct FAPIACommunication
*
* @brief This structure holds the necessary communication parameters.
*
*/
typedef struct
{
/// Possible communication error. If the error_code is not ok then the
/// whole transaction was canceled.
FAPIAError communication_error;
/// Id of the transaction. It is unique within this process.
unsigned long transaction_id;
/// Name of the logical object. Maybe e.g. the device_name.
char * logical_object_name;
/// Name of the physical source object. Needed for replies.
Requests do not
/// need to set it. It can be NULLL.
char * source_physical_object_name;
/// Priority of the transaction.
FAPIACommunicationPriority priority;
/// Indicates whether the caller likes to have a reply or not. This
is only
/// reasonable on write requests. Otherwise an error occurs.
unsigned char send_reply;
/// Number of entries. This belongs to the amount of FAPIAParameter,
/// FAPIAValue and FAPIAError elements following.
unsigned long number_of_entries;
} FAPIACommunication;
/**
* @enum FAPIACommunicationPriority
*
* @brief Priority of the Message. Default should be
* FAPIA_COMMUNICATION_PRIORITY_NORMAL.
*
*/
typedef enum
{
FAPIA_ACCESS_RIGHTS_READ = 1,
FAPIA_ACCESS_RIGHTS_WRITE = 2,
FAPIA_ACCESS_RIGHTS_READWRITE = 3
} FAPIAAccessRights;
/**
* @struct FAPIAInfo
*
* @brief This structure is used to hold information about a Parameter.
*
*/
typedef struct
{
/// Datatype of the value.
FAPIADataType data_type;
/// Length in bytes of the value.
unsigned long data_length;
/// Pointer to the minimum value. Dependend on the data_type
/// it must be casted.
void* min_value;
/// Pointer to the minimum value. Dependend on the data_type
/// it must be casted.
void* max_value;
/// Priority of the transaction.
FAPIAAccessRights access_rights;
/// Unit of the value.
char * unit;
/// Exponent of base 10 to determine value for corresponding unit.
/// If exponent is not used it must be 0.
long exponent;
/// Factor to determine value for corresponding unit.
/// If factor is not used it must be 1.
long factor;
/// Descriptoin of the parameter.
char * description;
} FAPIAInfo;
//=============================================================================
/**
* Functions
*/
//=============================================================================
/**
* @brief Initializes the FAPIA. name is the physical_object_name of this
* communication node.
*
* If it returns a negative number there was an error.
*
*/
long fapia_init (
int argc,
char* argv[],
const char * const name);
/**
* @brief Deinitializes the FAPIA. FAPIA has to deallocate all
allocated memory
* and shut down.
*
* If it returns a negative number there was an error.
*
*/
long fapia_deinit (void);
/**
* @brief Retrieves the logical object names from the FAPIA.
*
* If it returns a negative number there was an error.
*
*/
long fapia_logical_object_names (
char*** logical_object_names,
unsigned long* number_of_logical_object_names);
//-----------------------------------------------------------------------------
/**
* Callback setting functions
*/
//-----------------------------------------------------------------------------
/**
* @brief Initializing the caller for responses of read requests. FAPIA
holds a
* reference to the function and calls it when a response is received.
*
* If it returns a negative number there was an error.
*
*/
long fapia_set_callback_for_parameter_read_response_callback (
long (*f) (const FAPIACommunication *,
const FAPIAParameter *,
const FAPIAValue *,
const FAPIAError *));
/**
* @brief Initializing the caller for responses of write requests.
FAPIA holds a
* reference to the function and calls it when a response is received.
*
* If it returns a negative number there was an error.
*
*/
long fapia_set_callback_for_parameter_write_response_callback (
long (*f) (const FAPIACommunication *,
const FAPIAParameter *,
const FAPIAError *));
/**
* @brief Initializing the caller for responses of info requests. FAPIA
holds a
* reference to the function and calls it when a response is received.
*
* If it returns a negative number there was an error.
*
*/
long fapia_set_callback_for_parameter_info_response_callback (
long (*f) (const FAPIACommunication *,
const FAPIAParameter *,
const FAPIAInfo *,
const FAPIAError *));
/**
* @brief Initializing the callee for read requests. FAPIA holds a
* reference to the function and calls it when a request is received.
*
* If it returns a negative number there was an error.
*
*/
long fapia_set_callback_for_parameter_read_request_callback (
long (*f) (const FAPIACommunication *,
const FAPIAParameter *));
/**
* @brief Initializing the callee for write requests. FAPIA holds a
* reference to the function and calls it when a request is received.
*
* If it returns a negative number there was an error.
*
*/
long fapia_set_callback_for_parameter_write_request_callback (
long (*f) (const FAPIACommunication *,
const FAPIAParameter *,
const FAPIAValue *));
/**
* @brief Initializing the callee for info requests. FAPIA holds a
* reference to the function and calls it when a request is received.
*
* If it returns a negative number there was an error.
*
*/
long fapia_set_callback_for_parameter_info_request_callback (
long (*f) (const FAPIACommunication *,
const FAPIAParameter *));
//-----------------------------------------------------------------------------
/**
* Read functions
*/
//-----------------------------------------------------------------------------
/**
* @brief Sends a read request to the callee.
fapia_communication.transaction_id
* and fapia_communication.source_physical_object_name are filled out
by the
* FAPIA.
*
* If it returns a negative number there was an error.
*
*/
long fapia_parameter_read_request (
FAPIACommunication * const fapia_communication,
const FAPIAParameter * const fapia_parameters);
#if 0
/**
* @brief This is the callback response function of the read_request.
It is _not_
* implemented by FAPIA. This may be done by the caller application. A
function
* with this signature must be set by function
* fapia_set_callback_for_parameter_read_response_callback.
*
* If it returns a negative number there was an error.
*
*/
long fapia_parameter_read_response_callback (
const FAPIACommunication * const fapia_communication,
const FAPIAParameter * const fapia_parameters,
const FAPIAValue * const fapia_values,
const FAPIAError * const fapia_errors);
/**
* @brief This is the callback request function of the read_request. It
is _not_
* implemented by FAPIA. This may be done by the callee application. A
function
* with this signature must be set by function
* fapia_set_callback_for_parameter_read_request_callback.
*
* If it returns a negative number there was an error.
*
*/
long fapia_parameter_read_request_callback (
const FAPIACommunication * const fapia_communication,
const FAPIAParameter * const fapia_parameters);
#endif
/**
* @brief Sends a read response to the caller.
*
* If it returns a negative number there was an error.
*
*/
long fapia_parameter_read_response (
const FAPIACommunication * const fapia_communication,
const FAPIAParameter * const fapia_parameters,
const FAPIAValue * const fapia_values,
const FAPIAError * const fapia_errors);
//-----------------------------------------------------------------------------
/**
* Write functions
*/
//-----------------------------------------------------------------------------
/**
* @brief Sends a write request to the callee.
fapia_communication.transaction_id
* and fapia_communication.source_physical_object_name are filled out
by the
* FAPIA.
*
* If it returns a negative number there was an error.
*
*/
long fapia_parameter_write_request (
FAPIACommunication * const fapia_communication,
const FAPIAParameter * const fapia_parameters,
const FAPIAValue * const fapia_values);
#if 0
/**
* @brief This is the callback response function of the write_request.
It is _not_
* implemented by FAPIA. This may be done by the caller application. A
function
* with this signature must be set by function
* fapia_set_callback_for_parameter_write_response_callback.
*
* If it returns a negative number there was an error.
*
*/
long fapia_parameter_write_response_callback (
const FAPIACommunication * const fapia_communication,
const FAPIAParameter * const fapia_parameters,
const FAPIAError * const fapia_errors);
/**
* @brief This is the callback response function of the write_request.
It is _not_
* implemented by FAPIA. This may be done by the caller application. A
function
* with this signature must be set by function
* fapia_set_callback_for_parameter_write_response_callback.
*
* If it returns a negative number there was an error.
*
*/
long fapia_parameter_write_request_callback (
const FAPIACommunication * const fapia_communication,
const FAPIAParameter * const fapia_parameters,
const FAPIAValue * const fapia_values);
#endif
/**
* @brief Sends a write response to the caller.
*
* If it returns a negative number there was an error.
*
*/
long fapia_parameter_write_response (
const FAPIACommunication * const fapia_communication,
const FAPIAParameter * const fapia_parameters,
const FAPIAError * const fapia_errors);
//-----------------------------------------------------------------------------
/**
* Info functions
*/
//-----------------------------------------------------------------------------
/**
* @brief Sends a info request to the callee.
fapia_communication.transaction_id
* and fapia_communication.source_physical_object_name are filled out
by the
* FAPIA.
*
* If it returns a negative number there was an error.
*
*/
long fapia_parameter_info_request (
FAPIACommunication * const fapia_communication,
const FAPIAParameter * const fapia_parameters);
#if 0
/**
* @brief This is the callback response function of the info_request.
It is _not_
* implemented by FAPIA. This may be done by the caller application. A
function
* with this signature must be set by function
* fapia_set_callback_for_parameter_info_response_callback.
*
* If it returns a negative number there was an error.
*
*/
long fapia_parameter_info_response_callback (
const FAPIACommunication * const fapia_communication,
const FAPIAParameter * const fapia_parameters,
const FAPIAInfo * const fapia_infos,
const FAPIAError * const fapia_errors);
/**
* @brief This is the callback response function of the info_request.
It is _not_
* implemented by FAPIA. This may be done by the caller application. A
function
* with this signature must be set by function
* fapia_set_callback_for_parameter_info_response_callback.
*
* If it returns a negative number there was an error.
*
*/
long fapia_parameter_info_request_callback (
const FAPIACommunication * const fapia_communication,
const FAPIAParameter * const fapia_parameters);
#endif
/**
* @brief Sends a info response to the caller.
*
* If it returns a negative number there was an error.
*
*/
long fapia_parameter_info_response (
const FAPIACommunication * const fapia_communication,
const FAPIAParameter * const fapia_parameters,
const FAPIAInfo * const fapia_infos,
const FAPIAError * const fapia_errors);
#ifdef __cplusplus
}
#endif
#endif /* _FAPI_ACYCLIC_H_ */
*******************************************************************************
Regards,
Thomas Rothfuss
More information about the ag-automation
mailing list