IO-Link Device Stack v1.1 API User Guide

Transcription

1 IO-Link Device Stack v1.1 API User Guide

2 2

3 IO-Link Device Stack v1.1 The API user guide Document ID API_TEC_012_001 Author Péter Kaszás; Johannes Beuschel Issue Date Reviewed Status Release Version V1.1 3

4 Revision History Version Date Description Status Author Jan-14 Initial version A PK Apr-05 Added comments to ATmega port A PK Apr-19 Additional correction at few chapters, added Sync A PK Query description Apr-24 Document restructured M PK Sep-24 Added new API function for SIO handling A PK Jan-08 API extended with new functions, API list altered A+M PK and better described functionalities, updated related documents to the newest IO-Link interface specification Mar-10 New ISDU subsystem introduced with new API A PK callbacks for handling parameters outside of the stack Jul-04 New SIO API functions and new ComStateFlag A+M PK introduction Nov-04 Data Storage API redesign, A+M PK Status flags redesign, Temporary Interrupt vector installation methods, System Commands handler callback registrations, Device access locks API Apr-24 Update after revision of stack A+M+D JB Jun-01 Layout changes OW Jul : comment concerning checksum added. Function added: iold_api_get_accesslocks Function added: iold_api_register_ds_startblockparametercallback Function added: iold_api_localparameterchanged Kap : Description of function iold_api_register_ds_tempparametersetcheckerca llback updated. Kap : Functions added: iold_api_register_nvram_readdatacallback and iold_api_register_nvram_writedatacallback Kap 7: Revised A+M JB Status: M=Modified, A=Added, D=Deleted 4

5 1 Table of Contents 2 Scope Purpose of this document Applicable documents Acronyms and abbreviations IO-Link Device Stack concept Boot up procedure IO-Link Device Stack API Initialization API ISDU handling API Parameter Manager and Data Storage API Event Handling API Process Data Exchange API System Commands API Standard IO API System Management Temporary IVT API Non volatile RAM Configure the stack for the device application Enable/Disable IO-Link Stack modules Parameter Manager Module Configuration of the Page Parameters

6 4.2 ISDU Parameter ReadParam Callback WriteParam Callback Process Data Exchange module Asynchronous process data exchange Synchronous process data exchange Block Parameter Data Storage module Temporary parameter set Register Data Storage Parameter Start of a block parameter transfer Check current parameter set Store the temporary parameter set Drop the temporary parameter set Parameter Checksum CRC signature Revision counter Consistency check System command handling Device access locks API Event handler module Event API calls ISDU handler module System Management module Standard IO module

7 2 Scope 2.1 Purpose of this document The device application may use the IO-Link device stack using the stack API which is described in this document. The device application shall use the API functions for stack initialization and communication. These API functions provide easy access to the stack. The device application related algorithms can be implemented in separated source files. The device application can use all the IO-Link device application related IO-Link modules like the Data Storage, Parameter Manager, Event Dispatcher, and Process Data Exchanger to communicate and share data with the IO-Link stack. 2.2 Applicable documents Ref Doc-Identification Order No Document Title Date Version /1/ IOL-Interface- Spec_10002_V112_Jul13 /2/ TUT_ICBT_001_008_DeviceSta cktutorial.docx IO-Link Interface and System, specification IO Link Device Stack tutorial July November 0.2 7

8 2.3 Acronyms and abbreviations Acronym Description IOL IO-Link PL Physical Layer DL Data-link Layer AL Application Layer APP Device Application which uses the stack API functions. API Application Programing Interface UART Universal Asynchronous received/transmitter SPI Serial Peripheral Interface Bus SYSM System Management layer PM Parameter Manager DS Data Storage ED Event Dispatcher PDE Process Data Exchange PDin Input Process Data (PDin data is sent from Device to Master) PDout Output Process Data (PDout data is sent from Master to Device) u8 u16 u32 Unsigned char typedef Unsigned short typedef Unsigned long typedef 8

9 3 IO-Link Device Stack concept Figure 1 shows the IO-Link Device stack layers and services, and the basic structure of the IO-Link device stack. The device stack implementation contains all layers up to the highest level. The user application can reach the Data Storage and the Parameter Manager which are linked tightly to each other, the Event Dispatcher and the Process Data Exchange module. Figure 1: Device Stack structure (from /1/ page 151) Our IO-Link device stack implementation has a very easy approach to the IO-Link enabled sensor or actuator device implementations. The device application will implement the methods and actions to acquire process data, and handling events and parameters while the IO-Link stack will send out 9

10 these data and results for the IO-Link enabled and connected Master device. So if we want to classify the IO-Link enabled device software modules we have to distinguish 2 basic modules: The IO-Link device application (which is implemented by You) The IO-Link device stack (what TEConcept provide for You) IO-Link device application TEConcept IO-Link API interfaces IO-Link Stack TEConcept Hardware and Software abstaction layer for IO-Link Figure 2: Software modules of the IO-Link device The implemented API functions are not giving direct access to the stack itself. They are providing access to the upper IO-Link modules (Data Storage, Parameter Manager, Event Dispatcher and Process Data Exchanger) instead. This simplifies the handling of the IO-Link stack for the user application, because it removes the need of complex interaction with lower stack layers. The only thing what the user application has to do is, to assign parameters to the Data Storage + Parameter Manager, issue events if needed, and set or get process data. If any additional actions needed from the device application (like validation of new parameters, local behavior changes, etc.) the stack will call the registered API Callback functions. The callback function operations must be defined by the device application. Each device application will require different methods and actions what to do in these callbacks. It is up to the stack user space program (device application) programmer what to do in which cases. 10

11 The API functions are grouped; the following diagram is showing that which API belongs to which IO-Link modules. Data Storage Parameter Management Event Management Process Data Exchanger System management Standard IO ISDU handling functions Initilization Figure 3: IO-Link Stack API function groups 3.1 Boot up procedure The typical boot up procedure of the IO-Link stack is described below: First the iold_api_register () functions have to be called. Which functions have to be called depends on which stack modules are used. Next, iol_stack_initialization() has to be called, which will initialize all the necessary hardware elements and the basic stack layer structures. These are necessary for the essential stack functionality. The next step is to set up the basic stack parameter (direct parameter page one). This is done by calling iold_api_create_dpp1() with the appropriate parameters. If the used M-Sequence type is known at compile time (if you purchased the source code and not the object code only) the appropriate values are provided as defines. After this step the device application may initialize itself and the start running. 11

12 3.2 IO-Link Device Stack API In the following section the document will introduce TEConcept s IO-Link device stack API functions. For an better overview, every function, its arguments and its return value is described on a separate page. You can find the API in the file inc\iold_api.h. The API functions are organized in different groups according to its purposes. The API groups are the following: Initialization API ISDU handling API Parameter Manager and Data Storage API Event Handling API Process Data Exchange API System Commands API Standard IO API System Management Temporary IVT API 12

13 3.2.1 Initialization API [1] iol_stack_initialization Initialization of hardware and software modules of the device stack. Defines from iol_stack_config.h are used to configure the stack. Initialization API iol_stack_initialization() 13

14 3.2.2 ISDU handling API [2] iold_api_register_isduprewritecallback Register callback function. Callback is invoked, when an ISDU request from IOL master is received on data link layer, before the application layer calls ReadParamCallback or WriteParamCallback. ISDU handling API iold_api_register_isduprewritecallback (ISDUCallback_t p) p: Function pointer to the callback function 14

15 [3] iold_api_register_isdupostwritecallback Register callback function. Callback is invoked after ISDU request is handled and the response was sent to IOL master. ISDU handling API iold_api_register_isdupostwritecallback (ISDUPostCallback_t p) p: Function pointer to the callback function 15

16 [4] iold_api_register_readparamcallback Register callback function. The requested ISDU index and subindex is passed to the callback function. The callback function shall respond to the request with iold_api_isdu_sendresponse() if the index is readable or with one of the error response functions iold_api_isdu_create_error_response() or iold_api_isdu_create_vendor_specific_error_response() and an appropriate error code. ISDU handling API iold_api_register_readparamcallback (ParamRead_Callback_t p) p: Function pointer to the callback function 16

17 [5] iold_api_register_writeparamcallback Register callback function. The callback function shall check if the addressed ISDU parameter is writable, check if the data to write is valid and respond with an error or set the addressed parameter and respond with no error. One of the functions iold_api_isdu_create_error_response(), iold_api_isdu_create_vendor_specific_error_response() iold_api_isdu_sendresponse() or must be called to answer the request. It is possible to answer with iold_api_isdu_sendresponse(...,e_isdu_busy_response). The stack sends busy responses to the master until the user application invokes the function with E_ISDU_WRITEPOSITIVE_RESPONSE or calls one of the error response functions. If the request is answered with iold_api_isdu_sendresponse(...,e_isdu_inst_tmp_ivt_response), the stack switches to temporary interrupts, executed from RAM and sends continuously busy messages to the master. The user application can write to flash without stopping IOL communication. The stack returns to normal communication, when the user application calls iold_api_end_tmp_interrupts(). This function is not available for all processors. ISDU handling API iold_api_register_writeparamcallback (ParamWrite_Callback_t p) p: Function pointer to the callback function 17

18 [6] iold_api_isdu_create_error_response Error response to an ISDU request that shall be used in ReadParamCallback or WriteParam- Callback if an ISDU parameter cannot be read or written. The error code 0x80 is set. The additional error code must be specified by the caller. ISDU handling API iold_api_isdu_create_error_response (u8 additional_error_code) additional_error_code: Additional error code as defined in table C.1 of IOL specification 18

19 [7] iold_api_isdu_create_vendor_specific_error_response Vendor specific error response to an ISDU request that shall be used in ReadParamCallback or WriteParamCallback if an ISDU parameter cannot be read or written. The error code 0x81 is set. The additional error code must be specified by the caller. ISDU handling API iold_api_isdu_create_vendor_specific_error_response (u8 additional_error_code) additional_error_code: Additional error code as defined in table C.1 of IOL specification 19

20 [8] iold_api_isdu_sendresponse Define the response that is sent back to the IO-Link master. ISDU handling API iold_api_isdu_sendresponse (u8 *isdu_response, u8 isdu_len, E_ISDU_Response_t isdu_type) isdu_response: the pointer to a buffer which holds the response data data_len: the length of data in ISDU message isdu_type: can be: E_ISDU_BUSY_RESPONSE - to continuously send busy message until this function is called again with an other parameter or until one of the error response functions is called. E_ISDU_READPOSITIVE_RESPONSE - to indicate read request positively E_ISDU_WRITEPOSITIVE_RESPONSE - to indicate write request positively. isdu_response and data_len should be zero. E_ISDU_INST_TMP_IVT_RESPONSE - answer with busy and switch to temporary interrupt vector table. Respond busy from temporary interrupts until user calls iold_api_end_tmp_interrupts() This function is not available for all processors. 20

21 [9] iold_api_get_accesslocks Return the current access locks according to Table B.12 Note: The user application has to check if the local parametrization is unlocked before changing a ISDU parameter value by e.g. a teach in button. ISDU handling API u8 iold_api_get_accesslocks() 8 lower bits of current access locks. 21

22 3.2.3 Parameter Manager and Data Storage API [10] iold_api_get_parameterpage_value Returns the value at the requested parameter page index address. Parameter Manager and Data Storage API u8 iold_api_get_parameterpage_value (u8 index) index: Address of the target parameter value to set. Indices in range 16 to 31 refer to direct parameter page 2 value of the parameter. If the index is not available, zero is returned. 22

23 [11] iold_api_create_dpp1 Passes the values for the direct parameter page 1 to the stack. Parameter Manager and Data Storage API iold_api_create_dpp1 (u8 min_cycle_time, u8 mseq_capability, u8 revision_id, u8 process_data_in, u8 process_data_out, u16 vendor_id, u32 device_id) min_cycle_time: minimum cycle time. See B.1.3 mseq_capability: M-sequence capability. See B.1.4 revision_id: RevisionID. See B.1.5 process_data_in: Number and structure of input data. See B.1.6 process_data_out: Number and structure of output data. See B.1.7 vendor_id: Unique vendor identification. See B.1.8 device_id: Unique device identification. 23

24 [12] iold_api_set_parameterpage_value Write a new value into a parameter page. Parameter Manager and Data Storage API iold_api_set_parameterpage_value (u8 index, u8 value) index: Address of the target parameter value to set. Indices in range 16 to 31 refer to direct parameter page 2 value: Data to write to the parameter page 24

25 [13] iold_api_register_ds_tempparametersetcheckercallback Registers a callback function to check the validity of the current parameter set. The callback function has to all parameters in the current parameter set for consistency. The current parameter set (primary or temporary) is passed to the callback function by the parameter. Parameter Manager and Data Storage API iold_api_register_ds_tempparametersetcheckercallback (DS_TempParamSetChecker_t p) p: Function pointer to the callback function 25

26 [14] iold_api_register_tempparamsetdropcallback Registers a callback function to drop temporary parameter set. The callback function has reset the temporary parameter set and mark all entries as unchanged. Parameter Manager and Data Storage API iold_api_register_tempparamsetdropcallback (DS_TempParamsetDrop_Callback_t p) p: Function pointer to the callback function 26

27 [15] iold_api_register_ds_storenewparamscallback Registers a callback function to apply the changes of the temporary parameter set to the primary parameter set. Parameter Manager and Data Storage API iold_api_register_ds_storenewparamscallback (DS_Store_Callback_t p) p: Function pointer to the callback function 27

28 [1] iold_api_register_ds_startblockparametercallback Registers a callback function that notifies the user application, that a block parameter transfer started. The user application shall assure, that the temporary parameter set is identic to the primary parameter set (copy primary parameter set to temporary parameter set). Parameter Manager and Data Storage API iold_api_register_ds_startblockparametercallback(ds_startblockparamete r_callback_t p) p: Function pointer to the callback function 28

29 [2] iold_api_register_ds_generatechecksumcallback Registers a callback function to generate a checksum. The callback function generates and returns a checksum of the current parameter set. Note: The checksum is a 4 byte value. Make sure, that the MSB is placed in the first byte. Parameter Manager and Data Storage API iold_api_register_ds_generatechecksumcallback (DS_ChecksumGenerator_t p) p: Function pointer to the callback function 29

30 [3] api_get_current_parameterset Get the information, if the primary or secondary parameter set is currently used. Parameter Manager and Data Storage API E_ActiveParamset_t api_get_current_parameterset ( ) indicator for current parameter set 30

31 [4] iold_api_register_ds_registerindexlistcallback Register RegisterIndexList callback function. The callback function has to use the function iold_ds_api_assign_index_list() to register the index list in the stack. The callback is called when the stack is (re)initialized. Parameter Manager and Data Storage API iold_api_register_ds_registerindexlistcallback (DS_RegisterIndexList_t p) p: Function pointer to the callback function 31

32 [5] iold_ds_api_assign_index_list DS API - assign the DS_Index to the Index_List of parameter values. Parameter Manager and Data Storage API iold_ds_api_assign_index_list (u8 *ds_list_array, u8 list_size, u32 ds_size) ds_list_array: pointer to the array which will hold the index list list_size: size of the array which holds index_list array ds_size: value of the data storage size 32

33 [1] iold_api_localparameterchanged Call this function, when an ISDU parameter was changed by local parametrization e.g. a teach-in button. This function sets the store request to notify the IOL Master that data storage has to be updated. Note: The application shall assure that local parametrization is not locked by checking the current access locks with iold_api_get_accesslocks() Parameter Manager and Data Storage API bool_t iold_api_localparameterchanged() FALSE when command could not be performed because local parametrization is locked. TRUE on success 33

34 3.2.4 Event Handling API [2] iold_ed_api_create_error Call this function to rise an IOL error event which is send to the master. The device stack provides an event queue that holds up to six events. Calling this function inserts a new event into the queue. If the queue is full, it is up to the calling function to evaluate the return value and rise the event again later. The event done callback can be used to identify an empty event queue. Event Handling API bool_t iold_ed_api_create_error (E_EVENT_INSTANCE_t instance, E_EVENT_MODE_t mode, u16 eventcode) instance: Source of the event, typically E_EVENT_INSTANCE_APPLICATION mode: Defines the mode of the event eventcode: The event code number, refer to table D.1 of IOL specification for permissible values. TRUE if event is created FALSE event could not be created. It is up to the caller to rise the event again. 34

35 [3] iold_ed_api_create_warning Call this function to rise an IOL warning event. See iold_ed_api_create_error() for detailed description. The only differences is the event type. Event Handling API bool_t iold_ed_api_create_warning (E_EVENT_INSTANCE_t instance, E_EVENT_MODE_t mode, u16 eventcode) instance: Source of the event, typically E_EVENT_INSTANCE_APPLICATION mode: Defines the mode of the event eventcode: The event code number, refer to table D.1 of IOL specification for permissible values. TRUE if event is created FALSE event could not be created. It is up to the caller to rise the event again. 35

36 [4] iold_ed_api_create_notification Call this function to rise an IOL notification event. See iold_ed_api_create_error() for detailed description. The only differences is the event type. Event Handling API bool_t iold_ed_api_create_notification (E_EVENT_INSTANCE_t instance, E_EVENT_MODE_t mode, u16 eventcode) instance: Source of the event, typically E_EVENT_INSTANCE_APPLICATION mode: Defines the mode of the event eventcode: The event code number, refer to table D.1 of IOL specification for permissible values. TRUE if event is created FALSE event could not be created. It is up to the caller to rise the event again. 36

37 [5] iold_api_register_eventdonecallback Register callback function. The callback function is called after events were sent to IOL master and the event queue is empty again. Event Handling API iold_api_register_eventdonecallback (EventCallback_t p) p: Function pointer to the handler function 37

38 3.2.5 Process Data Exchange API [6] iold_pde_api_setpdin Function for asynchronous data transfer. Process data given in pdin is copied and will be sent to the master with the next IOL telegram. The length of the process data depends on the used M-sequence type and is defined by PDIN_LEN in iold_stack_config.h. Event Handling API iold_pde_api_setpdin (u8 *pdin) pdin: pointer process data to be sent to the master 38

39 [7] iold_pde_api_getpdout Function for asynchronous data transfer. The function copies the latest process data received from IOL to the given memory address. The number of bytes depends on the used M- sequence type and is defined by PDOUT_LEN in iold_stack_config.h. Event Handling API iold_pde_api_getpdout (u8 *pdout) pdout: pointer to the array where the PDout data shall be copied. 39

40 [8] iold_pde_api_setpdvalidity Function for asynchronous data transfer. Set the validity of the PDIN data. To assure data consistency the user application must assure that the stack does not run between calls of iold_pde_api_setpdin() and iold_pde_api_setpdvalidity(). Event Handling API iold_pde_api_setpdvalidity (E_IOLD_PDE_VALIDITY_t pdvalidity) pdvalidity: PD validity value 40

41 [9] iold_pde_api_getpdvalidity Function for asynchronous data transfer. Function returns the validity value of the latest process data received. To assure data consistency the user application must assure that the stack does not run between calls of iold_pde_api_getpdout() and iold_pde_api_getpdvalidity(). Event Handling API E_IOLD_PDE_VALIDITY_t iold_pde_api_getpdvalidity () validity of latest process data 41

42 [10] iold_api_register_pdoutcallback Register callback function to acquire PDout data. In the callback function, the latest PDOUT data from IOL master can be processed. Event Handling API iold_api_register_pdoutcallback (PDCallback_t p) p: Function pointer to the callback function 42

43 [11] iold_api_register_pdincallback Register callback function to set PDin data for the next IOL telegram. The callback function writes the current PDIN data to the parameter and uses iold_pde_api_setpdvalidity() to set the validity. The callback is invoked after each stack run. Event Handling API iold_api_register_pdincallback (PDCallback_t p) p: Function pointer to the callback function 43

44 3.2.6 System Commands API [12] iold_api_register_vendorspecificsystemcommandcallback Register function to handle vendor specific system commands. The callback function has to handle all vendor specific system commands and shall return an error code, if the specified command is not available. It is called, when a command is written to ISDU index 2. System Commands API iold_api_register_vendorspecificsystemcommandcallback (DS_VendorSpecificSystemComamnd_Callback_t p) p: Function pointer to vendor specific system command handler 44

45 [13] iold_api_register_specialsystemcommandcallback Register function to handle special system commands. The commands to handle are device reset, application reset and factory reset. System Commands API iold_api_register_specialsystemcommandcallback (DS_SpecialSystemCommand_Callback_t p) p: Function pointer to special system command handler 45

46 3.2.7 Standard IO API [14] sio_api_set_sio_level Function to set the SIO output level. It is only applied, if the current mode is SIO mode. Standard IO API sio_api_set_sio_level (E_SIO_SIOLEVEL_t level) level: Output level to set. 46

47 [15] sio_api_set_sio_mode Function to set the SIO mode. It is only applied, if the current mode is SIO mode. Standard IO API sio_api_set_sio_mode (E_SIO_SIO_OUTPUT_MODE_t sio_mode) sio_mode: SIO mode to set (PNP/NPN/PP) 47

48 3.2.8 System Management [16] iold_api_get_devicemode Function returns the state of the system management state machine of the IOL stack. System Management E_IOLD_SYSMSTATE_t iold_api_get_devicemode () Return current state of IOL stack 48

49 [17] iold_api_register_compatibilitycheckcallback Register a function that performs the compatibility check. The callback functions has to check, whether the Device ID in direct parameter page 1 is supported and has to load the according parameters. If the Device ID is not supported, the callback function has to reset the Device ID in direct parameter page 1 to an ID that is supported and load the according parameters. System Management iold_api_register_compatibilitycheckcallback (CompatibilityCheck_Callback_t p) Function pointer to the callback function 49

50 3.2.9 Temporary IVT API [18] iold_api_end_tmp_interrupts API function that stops usage of the temporary IVT. The user calls this function to switch back to normal IOL communication, typically after writing to flash finished. Switch to standard IOL communication is performed, after the next busy telegram was sent. Temporary IVT API iold_api_end_tmp_interrupts (bool_t success) success: set true, when ISDU response shall be positive write response, set false, when an error response shall be sent. 50

51 [19] iold_api_tmp_ivt_installed Return the status of temporary interrupt vectors. Temporary IVT API bool_t iold_api_tmp_ivt_installed () true when temporary IVT is currently installed false when IVT in flash is used. 51

52 Non volatile RAM The stack needs to store some value in non-volatile RAM. As it is project dependent how nonvolatile RAM is accessed, callback functions to read from non-volatile RAM and to write to nonvolatile RAM are introduced. It is up to the user to implement the actual access to non-volatile RAM. [1] iold_api_register_nvram_readdatacallback Register callback function that reads data from NVRAM. The IOL stack has to store some values non volatile. As the CPU may not be blocked while reading from or writing to NVRAM, the user application has to execute project specific code (e.g. writing to an external EEPROM). The callback function shall return instantly. Time consuming commands shall be executed in a background process. It is suggested to mirror the content of the NVRAM in RAM, read the NVRAM on startup and write to NVRAM always when the content of the mirror changed. ISDU handling API iold_api_register_nvram_readdatacallback(nvram_readdatacallback_t p) p: Function pointer to the callback function 52

53 [1] iold_api_register_nvram_writedatacallback Register callback function that write data to NVRAM. The IOL stack has to store some values non volatile. As the CPU may not be blocked while reading from or writing to NVRAM, the user application has to execute project specific code (e.g. writing to an external EEPROM). The callback function shall return instantly. Time consuming commands shall be executed in a background process. It is suggested to mirror the content of the NVRAM in RAM, read the NVRAM on startup and write to NVRAM always when the content of the mirror changed. ISDU handling API iold_api_register_nvram_writedatacallback(nvram_writedatacallback_t p) p: Function pointer to the callback function 53

54 3.3 Configure the stack for the device application In our IO-Link device stack implementation we introduced a simple stack configuration system. The concept is that we provide an easy-to-use and easy-to-configure solution. Every IO-Link device has few very basic parameters which are stored on the Direct Parameter Page 1 and in the ISDU data object set. There are three configuration files for the stack. iol_stack_components.h, iol_stack_config.h and hw_config.h. The next paragraphs describe the content of the configuration files. iol_stack_components.h: This file contains the stack components that are included in the compilation. If you have purchased the object code of the stack, all components are included. If you have purchased the source code of the stack, you can reduce code size by commenting out components you do not want to use. Please note the hierarchical structure of some components. E.g. if you want to use events, you also of to activate the component ISDU. Please refer to the comments in the file for a description of the stack component. iol_stack_config.h: This file contains the application specific defines. Here you can define parameter strings like vendor name and product name and you can configure the IO-Link communication (M-Sequence Type, number of PDIN and PDOUT data etc.). Refer to the comments of the defines for a description. If you purchased object code of the stack, you also have to define the entries of the direct parameter page one. Comments in the file give you a hint where to gather the information and references to the according chapter in the IOL specification. hw_config.h: This file contains the hardware specific configuration. It contains the processor pin configuration, clock- and timer setup and the setup of the IOL-PHY. The configuration depends on the hardware you use. If you have to change something, refer to the comments of each define Enable/Disable IO-Link Stack modules If you have the stack in source code version you are able to add/remove some IO-link stack modules. This can save code size and can reduce the complexity of your application. Table 1 gives an overview over the stack components defined in iol_stack_components.h. 54

55 Define name VARIABLE_COM_SPEED Purpose Define this, if the used COM SPEED is not known at compilation time. This must be always defined, if you have an object code version of the stack. VARIABLE_M_SEQUENCE_TYPE _WITH_SIO _WITH_DEVACCESSLOCKS _WITH_ISDU _WITH_EVENTS _WITH_TEMPIVT _WITH_BLOCKPARAMS _WITH_DS _WITH_SYSCMD_DEFAULT _WITH_SYSCMD_PROFILE _WITH_SYSCMD_DEVRESET _WITH_SYSCMD_APPRESET _WITH_SYSCMD_FACTORYRESET Define this, if the used M-Sequence type is not known at compilation time. This must be always defined, if you have an object code version of the stack. Define this, if you want to use SIO mode. Built-in access locks mechanism support Enable ISDU communication Enable EVENT handling Used to add support for temporary interrupt vector. This is useful if you want to save data to the FLASH and the CPU stops while erasing the FLASH. The mechanism supports a limited IO-Link communication (just send busymessages) from RAM while code from FLASH is not available. After writing to FLASH finished, you can return to normal IO-Link communication by using an API function. If this feature is supported depends on the processor used. Enable Block Parameter support Enables Data Storage mechanism support Used to enable system command handling for regular block parameter handling Used to add support for profile system commands. Used to add support for Device Reset system command Used to add support Application reset system command Used to add support for Factory reset system command 55

56 _WITH_SYSCMD_CUSTOM Used to add support for Vendor specific system command _WITH_EVENTDONECALLBACK V1_0_COMPATIBLE _WITH_DEVICE_BACKWARD_COMPATI BILITY _CRC_ONLY_ON_READOUT Event done callback can be remove from stack to save code size by uncommenting this define. Define this, if the V1.1 device is compatible to the V1.0 specification. Define this, if the device shall be compatible to previous device implementations. If this is defined, the compatibility check function that checks the compatibility and sets up the compatible device must be registered with iold_api_register_compatibilitycheckcallback(). Define this, if a change of the data storage parameters can be detected by the callback function registered with iold_api_register_compatibilitycheckcallback(). If the callback function calculates a real checksum of the data storage parameters, it is only called, when the checksum is read. If the callback function just increments the checksumvalue on every write access to data storage parameters, this define must be uncommented. Table 1: Stack components 56

57 4 Parameter Manager Module There are two IOL-Link parameter types (page parameter and ISDU parameter) and according handling mechanisms. See /1/ Annex B for a detailed description. Page parameters are accessed by the page communication channel. They organized in two pages containing 16 bytes each. The direct parameter page 1 contains information about the IOL-Link configuration and must be set by the user application. Direct parameter page 2 is vendor specific and only used in small applications, that do not support ISDU parameters. ISDU parameters give extensive possibilities to configure the device including block parameters and data storage. 4.1 Configuration of the Page Parameters According to the IO-Link specification the implementation of the direct parameter page 1 (DPP1) is mandatory on every IO-Link enabled device. DPP1 holds the basic and mandatory information for IO-Link communication parameters, the basic device identification parameters, and the application controlling related parameters. The content and possible values of DPP1 can be found in /1/ table B.1. Furthermore Appendix B.1 describes the direct parameter pages and their content. The definition of DPP1 and DPP2 parameters is very easy using the API functions. Use iold_api_create_dpp1() for initial setting up DPP1. Single values of both direct parameter pages can be read and set by use of the functions iold_api_get_parameterpage_value() and iold_api_set_parameterpage_value() respectively. 4.2 ISDU Parameter ISDU parameter give extensive possibilities to configure a IOL Device. Some parameters are predefined by the IOL specification and it is possible to define application specific parameters. For the full parameter definition see /1/ Annex B. ISDU parameters must be defined in the application memory space. The application has to grant access to the parameters by callback functions ReadParam_Callback(u16 index, u8 subindex) and WriteParam_Callback(u16 index, u8 subindex, u8 * databuff, u8 datalen) that are registered in the stack with the functions iold_api_register_readparamcallback() and iold_api_register_writeparamcallback() respectively. In case the mechanisms Blockparameter or DataStorage are used, the application has to provide a temporary parameter set. The temporary parameter set is used to transmit several parameters from Master to Device, check the validity of the parameters as block and activate them all in the same cycle. 57

58 4.2.1 ReadParam Callback ReadParam_Callback gets and index and subindex which identify the parameter that is requested by the master. The callback function shall return this parameter with the API function iold_api_isdu_sendresponse() or if an error occurs, it should return an appropriate error message with iold_api_isdu_create_error_response() WriteParam Callback WriteParam_Callback gets an index and subindex of a parameter to set in the Device and a buffer databuff that contains the data to set. The callback function has to check if index and subindex are valid, e.g. check if the index is available and writable. It also has to check if the data length of the provided data is correct. In case of an error, this shall be signaled to the stack by using iold_api_isdu_create_error_response(). Then it must be decided, if the value shall be written to the parameter (primary parameter set) or to the temporary parameter. Which parameter set shall be used can be figured out by calling the AP function api_get_current_parameterset(). If the function returns E_PRIMARY_PARAMSET the callback function has to write to primary parameter set. Otherwise it has to write to the secondary parameter set. Finally, if the primary parameter set is used, the consistency of the data shall be checked before applying data to the parameter. If the temporary parameter set is used, the consistency check is performed later by the stack by calling the TempParameterSetChecker_Callback(). If no error occurred this shall be signaled to the stack with iold_api_isdu_sendresponse(0, 0, E_ISDU_WRITEPOSITIVE_RESPONSE). In any other case, an appropriate error shall be set using the API function iold_api_isdu_create_error_response(). 58

59 5 Process Data Exchange module The purpose of the Process Data Exchanger (PDE) module is to cyclically transfer the process data from the device application data buffer to the IO-Link stack and vice versa. All the octets of data types larger than 1 octet shall be "big endian" coded for transmission, i.e. the most significant octet (MSO) shall be sent first, followed by less significant octets in descending order, with the least significant octet (LSO) being sent last, as shown in Figure 4. Figure 4: Memory storage and transmission order for WORD based data types (from /1/ page 32. Chapter 3.3.6, Figure 2) The Process Data Exchanger module can be used with two different methods: Asynchronous process data exchange Synchronous process data exchange (with callback function) 5.1 Asynchronous process data exchange The user application shall pass the PDin data to the stack using the following command: iold_pde_api_setpdin(u8 * pdin); pdin points to the memory address, where the PDIN data are located in the user application, typically an array. The number of bytes copied from there is globally defined in PDIN_LEN. For receiving output process data from the master the device application shall use: iold_pde_api_getpdout(u8 * pdout). 59

60 The argument pdout is a pointer to the first element of the array where the output process data bytes shall be stored. The number of output process data is globally defined in PDOUT_LEN. The validity of the process data PDIN can be set with iold_pde_api_setpdvalidity(). Be aware that the assignment of validity and process data can be wrong, if the process of setting pdin data and pdin validity is interrupted by a stack run. If the function of setting process data invalid is used, it is advised to use the synchronous process data exchange, described in the next paragraph. The validity of process data PDOUT can be retrieved with iold_pde_api_getpdvalidity(). 5.2 Synchronous process data exchange The user application may send PDOUT data or process PDIN data synchronously with the IOL communication cycles. This is done by using callback functions that copy data from the user application to the stack and vice versa. The callback functions are registered with iold_api_register_pdoutcallback() and iold_api_register_pdincallback(). The PDIN callback function shall copy the process data to the buffer addressed in the parameter and use the API function iold_pde_api_setpdvalidity()to set the validity of the data. The PDOUT callback function shall check the validity of the PDOUT data by calling iold_pde_api_getpdvalidity() and then process the data addressed by the function parameter. 60

61 6 Block Parameter Usage of block parameters enables the master to transmit several parameters successively and perform the validity check for all parameters in one cycle. While transmitting the parameters they are stored in the temporary parameter set of the Device. After successful validation they are applied to the primary parameter set. Please note that all writeable parameters must be included in the temporary parameter set, if block parameters are enabled in the ISDU. The mechanism is controlled by predefined system commands. The user has to provide the following callback functions that are used by the block parameter mechanism. DS_DropTemporaryParamset_Callback() This function shall drop the temporary parameter set. According to IOL Specification that means hat all parameters in the temporary parameter set shall be marked as invalid. An easier approach is, to copy all parameters from the primary parameter set to the temporary parameter set so that both parameter sets are synchronized. DS_StoreNewParams_Callback() This function shall copy all parameters from the temporary parameter set that are marked as changed to the primary parameter set. An easier approach is to copy all parameters from temporary parameter set to primary parameter set. This can be done, if both parameter sets were synchronized before. TempParameterSetChecker_Callback() This function shall check all changed parameter in the temporary parameter set for validity and return valid or invalid. DS_ChecksumGenerator_Callback() This function shall return a checksum of the temporary parameter set. The checksum is used to detect changes of the parameter set. The callback is called on every change of the temporary parameter set. If primary parameter set and temporary parameter set are synchronized with the DropTemporaryParameterset_Callback, this function can simply increment the checksum. 61

62 7 Data Storage module To use Data Storage it must be activated in the stack with the define _WITH_DS. It is not necessary to activate block parameterization. The application has to register all parameters in the stack that shall be included in the data storage. The application has to implement several callback functions to handle DataStorage. The following paragraphs explain step by step how to implement DataStorage 7.1 Temporary parameter set First of all the application must implement a temporary parameter set. If Blockparameters or DataStorage is active in the ISDU, for every writeable ISDU parameter a temporary parameter with the same type and size must exist. In the write callback function the application has to write either to the primary parameter or to the temporary parameter dependent on the return value of api_get_current_parameterset(). The read callback function always returns values from primary parameter set. 7.2 Register Data Storage Parameter The application has to assign the index list holding all ISDU parameters included in DataStorage using the function iold_ds_api_assign_index_list(). This function must be called from a callback function registered with iold_api_register_ds_registerindexlistcallback(). See Table B.11 in /1/ for a description of the index list. 7.3 Start of a block parameter transfer When a block parameter transfer is started by the Master or when a DataStorage download starts, the callback function registered with iold_api_register_ds_startblockparametercallback() is called. From this moment on, the temporary parameter set is used. So the application has to assure in the callback function that the temporary parameter set is a copy of the primary parameter set. If no other mechanisms are used to synchronize primary and temporary parameter set, the callback function shall simply copy the primary parameter set to the temporary parameter set. Note: After a block transfer has started, the local parametrization is locked. Make sure that the application checks the access locks (get them with iold_api_localparameterchanged()) before changing a parameter by local parametrization. 7.4 Check current parameter set iold_api_register_ds_tempparametersetcheckercallback() registers a callback function that checks the current parameter set (the current parameter set can be got with api_get_current_parameterset()) for consistency. The callback function e.g. checks for overlapping set points. The whole parameter set must be checked. 7.5 Store the temporary parameter set On the end of a block transfer and after the temporary parameter set is checked and valid, the stack calls the callback function that stores the temporary parameter set. This callback function is registered with iold_api_register_ds_storenewparamscallback(). The callback function shall copy the 62

63 temporary parameter set to the active parameter set. As the temporary parameter set was synchronized on start of the block transfer, there is no need to check which parameter changed and the complete parameter set can simply be copied. 7.6 Drop the temporary parameter set When a block transfer is aborted by the master, the stack calls the callback function registered with iold_api_register_tempparamsetdropcallback(). The temporary parameter set shall be dropped (e.g. copy primary parameter set to temporary parameter set). The implementation might be optional, if the application can assure that the temporary parameter set is not used before it is synchronized with the primary parameter set. 7.7 Parameter Checksum A checksum is designed to identify a changed parameter set. The Master uses the checksum to identify that a device was exchanged and that a parameter download to the new device is necessary. The IOL Specification /1/ suggests two methods of implementation CRC signature The checksum is a CRC signature of the parameter set. The checksum has to be updated only when it is read by the Master. Therefore _CRC_ONLY_ON_READOUT must be defined in iol_stack_compo nents.h. The callback function registered with iold_api_register_ds_generatechecksumcallback() is always called when the checksum is read by the Master and shall calculate the checksum over the whole parameter set Revision counter The checksum can also be implemented as an revision counter. The callback function is always called when the parameter set is changed. (After a single parameter transfer, the checksum is not updated. It is updated, when the master sends the DownloadStore system command) The callback function can simply increment the checksum value. 7.8 Consistency check According to IOL Specification the consistency of the parameter set shall be checked when writing a single parameter or at the end of a parameter block transfer. If the parameter set is not valid the new parameter(s) shall be discarded. For the implementation this means: If the current parameter set is the primary parameter set (that is true for single parameter transfers), the consistency of the parameter set shall be checked before accepting the new parameter. This is typically done in the WriteParamCallback function registered with iold_api_register_writeparamcallback(). If the current parameter set is the temporary parameter set (this is true after the start of a block parameter transfer or after an DataStorage download), the WriteParamCallback just writes the parameter to the temporary parameter set without checking for consistency. However the data structure and the validity (e.g. limits) of single parameters is checked. At the end of the block transfer or 63

64 DataStorage download, the function TempParameterSetChecker_Callback is called. This function checks the complete parameter set for consistency. 8 System command handling System commands are a method to trigger an action in the device stack or in the device application by sending a command from the IOL Master. System commands must be activated with the appropriate switch in iol_stack_components.h. For application specific system commands a callback function that handles the command must be implemented and registered to the stack with the function iold_api_register_vendorspecificsystemcommandcallback(). There are some additional predefined system commands for device reset, application reset and to restore factory settings. This commands must be handled by the application in a callback function, that is registered with iold_api_register_specialsystemcommandcallback(). 9 Device access locks API The supported device access locks can be selected by setting the define SUPPORTED_ACCESS_LOCKS. The define should be located in iol_stack_config.h. 64

65 10 Event handler module If the device application needs to inform the master about the occurrence of a specific event, this can be done by calling one of the following API functions: bool_t iold_ed_api_create_error(e_event_instance_t instance, E_EVENT_MODE_t mode, u16 eventcode); bool_t iold_ed_api_create_warning(e_event_instance_t instance, E_EVENT_MODE_t mode, u16 eventcode); bool_t iold_ed_api_create_notification(e_event_instance_t instance, E_EVENT_MODE_t mode, u16 eventcode); 10.1 Event API calls The first two parameters of each of the calls use specific struct-parameters as defined below: typedef enum{ E_EVENT_INSTANCE_UNKNOWN = (u8)0x00, E_EVENT_INSTANCE_RESERVED1 = (u8)0x01, E_EVENT_INSTANCE_RESERVED2 = (u8)0x02, E_EVENT_INSTANCE_RESERVED3 = (u8)0x03, E_EVENT_INSTANCE_APPLICATION = (u8)0x04, E_EVENT_INSTANCE_RESERVED5 = (u8)0x05, E_EVENT_INSTANCE_RESERVED6 = (u8)0x06, E_EVENT_INSTANCE_RESERVED7 = (u8)0x07 } E_EVENT_INSTANCE_t; In most cases events are issued by the application instance, then E_EVENT_INSTANCE_APPLICATION shall be used for instance. In any other case E_EVENT_INSTANCE_UNKNOWN shall be used. typedef enum{ E_EVENT_MODE_RESERVED = (u8)0x00, E_EVENT_MODE_SINGLESHOT = (u8)0x01, E_EVENT_MODE_DISAPPEARS = (u8)0x02, E_EVENT_MODE_APPEARS = (u8)0x03 } E_EVENT_MODE_t; The Event Mode takes the value E_EVENT_MODE_APPEARS when the device application wants to indicate that new event happened on the device. For example an over temperature event is signaled with the mode E_EVENT_MODE_APPEARS. When the temperature is back in the specified range, this can be signaled with an E_EVENT_MODE_DISAPPEARS event. The E_EVENT_MODE_SINGLESHOT mode can be used in cases when the device application wants to report an event which can happen only once and no further actions or indication is needed (see /1/ Table A.20). 65