DALI 2 Framework Design Document Introduction System Requirements Hardware Requirements Software Requirements...

Transcription

1 DALI 2 Framework Design Document Version Introduction This project provides a Synergy Platform compatible Framework for the Digital Addressable Lighting Interface (DALI; International standard IEC and IEC 62386) in Version 2. It uses the DALI interface of S128 MCUs und the ThreadX RTOS (optional) and provides libraries to be integrated in user applications. With its help it is possible to develop devices conforming to the DALI 2 standard. The DALI 2 framework consists of a HAL Driver for the MCUs interface, a Framework Driver encapsulating additional timing functionality and an optional Library Framework that supplies higher level DALI functions. Contents DALI 2 Framework Design Document Introduction System Requirements Hardware Requirements Software Requirements Design Overview HAL Driver Overview... 2 Timing and Interrupt Context Operation Framework Driver Overview Library framework: Overview and Configuration Memory Usage Architecture block diagram... 21

2 2. System Requirements 2.1 Hardware Requirements Synergy S128 MCU with DALI 2 interface (for example R7FS128783A01CFM). CPU speed >= 32 MHz Memory requirements: 256 KB Flash, 24 KB RAM The development board DK-S128 may be used. It fulfills all hardware requirements and includes a hardware interface for a direct DALI bus connection. 2.2 Software Requirements The Framework is developed to be used with e2studio. You need a PC with e2studio ISDE Version or newer. SSP version gcc embedded ARM Toolchain version or newer Renesas Synergy MCU S128 Pack file (Renesas.Synergy_mcu_s pack) 3. Design Overview The DALI 2 framework consists of 1. HAL Driver: It uses the MCUs DALI interface to receive and send DALI frames. 2. Framework Driver: It encapsulates the HAL driver and a general purpose timer (GPT) that is needed by the HAL driver for additional timing. 3. Library Framework: (optional). It implements higher level DALI requirements and functions and uses the Framework driver. 4. Application: The user application can either use the Framework driver and work with DALI frames directly or it can use the Library Framework that implements lots of DALI-specific requirements. 3.1 HAL Driver Overview The HAL Driver uses the MCU s DALI interface to send and receive DALI frames. It provides an API to control the interface and to send frames. A callback function must be provided to receive DALI frames and status information. The HAL Driver performs DALI-specific timing and time measurements. To do so an accurate time source must be supplied. Page 2

3 3.1.1 Configuration The configuration of the module is done in the Properties dialog of the module within e2studio. Module-specific properties Name: Name of the control variable Channel: Number of the DALI interface to be used (0 for S128 R7FS128783A01CFM) Transmission timeout [100 usec]: If sending a frame within this time is not possible, sending is aborted and the callback function is called with an error status. Use 0 if no timeout is needed. Time is given in increments of 100 usec. For example, a number of 2000 represents a time of 200 msec. Periodic status transmission [100 usec]: If not 0 the callback function will be called in the given time interval with the DALI interface status. It is used by the Library Framework. If the Library Framework is not used it can be used by the application for timing purpose and may eliminate the need for additional timers. Callback: Must be provided if the Library Framework is not used. The provided callback must have the prototype: void callback (dali_frame_t p_frame). For details of the returned dali_frame_t variable, see the complete API documentation or the DEMO code. The callback will be called when a DALI frame is received. when a DALI frame was sent successfully or could not be sent (timeout). periodically if Periodic status transmission is not 0. Collision detection: Enable or disable DALI collision detection (for details see datasheet of S-128 MCU and/or DALI spec). Page 3

4 Strict collision detection: Enable or disable strict DALI collision detection (for details see datasheet of S-128 MCU and/or DALI spec). Bit timing violation detection: Enable or disable timing violation detection (for details see datasheet of S-128 MCU and/or DALI spec). DTX width modulation: Enable or disable DTX width modulation. All DALI hardware interfaces have a delay in their sending circuit between the MCU s DALI Tx output to the DALI bus. If the delay of the falling edge and the rising edge is not the same, the signal on the DALI bus gets misshaped. The resulting signal at the DALI bus does not have the correct half-bit timing. If the amount of this misshape is known it can be compensated with the help of the DTX width modulation. low time of DTX in usec [ ]: Time in usec the DALI Tx pin of the MCU should remain low to achieve an optimal DALI bus low time of usec. Only used if DTX width modulation is active. Falling Edge Interrupt Priority: Must be enabled and set properly. Default priority is 2. Stop Detection Interrupt Priority: Must be enabled and set properly. Default priority is 2. Buspower Down Interrupt Priority: Must be enabled and set properly. Default priority is 2. Collision Detection Interrupt Priority: Must be enabled and set properly. Default priority is 2. Configuring the DALI interface Clock Source The DALI interface of the S128 MCS uses PCLKB as clock source. The HAL Driver supports the following clock frequencies: 4,8,12,16,24,32,48 and 64MHz. Open the Clocks configuration menu of your application and make sure that PCLKB is set to one of these frequencies. Page 4

5 3.1.2 API Usage The HAL Driver defines APIs for controlling the DALI interface and sending frames. A complete list of the available APIs, an example API call, a short description of each and the API status return values can be found in the tables below. For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the API References Manual for the module. Function name.open.close Example API Call and Definition g_dali0.p_api->open(g_dali0.p_ctrl, g_dali0.p_cfg) This API must be called once before using the DALI interface. It will initialize and open the DALI interface. g_dali0.p_api close(g_dali0.p_ctrl) This API can be called to shut down the DALI interface. It will clean-up and close the DALI interface. Before the interface can be used again, a call to open is necessary..write dali_frame_t frame; // declare frame variable frame.data_length=16; // send a 16 bit frame frame.data=0xa701; // data to be send frame.priority=dali_frame_priority_3; // send with priority 3 g_dali0.p_api->write(g_dali0.p_ctrl, &frame); This API must be called to send a DALI frame. frame must be of type dali_frame_t and filled with the necessary information..infoget.versionget.timinghelper dali_info_t info; // declare variable that will receive the information g_dali0.p_api infoget(g_dali0.p_ctrl, &info); This API can be called to retrieve status and statistical information about the DALI interface. g_dali0.p_api->versionget(&version); Retrieve the API version with the version pointer. Can be called even if the interface is not opened. g_dali0.p_api->timinghelper(g_dali0.p_ctrl) This API must be called every 100 usec if the interface is opened. This way the driver can meet the DALI timing requirements. This is done automatically by using the Framework Driver. Table 1: HAL driver API Each call to an API will return a status return value listed below. Name SSP_SUCCESS SSP_ERR_ASSERTION Description API call successful. NULL pointer argument Page 5

6 SSP_ERR_DALI_INIT_FAILED SSP_ERR_DALI_INTERFACE_NOT_OPEN SSP_ERR_DALI_TRANSMIT_NOT_READY SSP_ERR_DALI_ILLEGAL_FRAMELENGTH SSP_ERR_DALI_ILLEGAL_PRIORITY SSP_ERR_DALI_UNSUPPORTED_FREQ Initialization of DALI interface failed Interface was not opened Request to send a frame while transmitter is not ready Request to send a frame with unsupported length Request to send a frame with unsupported priority DALI interface is supplied with an unsupported clock frequency. Table 2: API return codes Operation Initialization The configuration of the interface is done by setting its properties in the e2 studio. The DALI interface is then initialized and un-initialized by calling its API open and close functions. However, this is normally NOT done from the application, because the Framework Driver will call these functions when it is opened/closed. Sending DALI frames DALI frames can be sent by calling the.write API function. The call can only succeed if no other frame is pending within the HAL driver. The application must make sure to wait until completion of a previous transmission or resend on an unsuccessful.write API call. The API function will always return immediately without waiting for the actual transmission of the frame to the DALI bus. The completion of the transmission will be indicated by calling the callback function. This will be done even on transmission failure or timeout. Receiving DALI frames If a DALI frame is received from the bus, the callback function will be called. Retrieving status information Statistics and status information can be retrieved any time while the interface is opened by calling the API.infoGet function. Timing and Interrupt Context Operation Care must be taken not to interfere with the critical timing of the HAL Driver. Interrupts with higher priority than the interrupts of the HAL Driver should be as short as possible. The HAL Drivers timing depends on the accuracy of the calls to its.timinghelper function. These calls should be as accurate as possible and no call should be left out while the interface is opened. It is best to use the Framework Driver that adds the correct timing to the HAL Driver automatically. The callback function should return as fast as possible and should not do any lengthy calculation, because it is called from an interrupt context. It is best to do the actual processing in another thread and not in the callback function itself. This is done automatically if the Library Framework is used. Critical sections in the application should be avoided or as short as possible because they may delay interrupt processing and make timing inaccurate. Page 6

7 3.1.4 Threads The HAL driver does not depend on ThreadX and does not use any threads. It is mainly interrupt-driven by either the DALI interface interrupts or timer interrupts Application The Application should not use the HAL Driver directly. Instead, it should use the Framework Driver or the Library framework. Page 7

8 3.2 Framework Driver Overview It encapsulates the HAL Driver and a general purpose timer (GPT) that is needed by the HAL Driver for additional timing. Its usage is very similar to the usage of the HAL Driver. It is a little easier because the handling of the additional timing and API function is not necessary. It also provides an API to control the interface and to send frames. A callback function must be provided to receive DALI frames and status information Configuration The configuration of the module is done in the Properties dialog of the module within e2studio. Configuration of the Framework driver s properties Name: Name of the control variable. Callback: Must be provided. It must have the prototype void callback (dali_frame_t p_frame); For details of the returned dali_frame_t variable, see the complete API documentation or the DEMO code. The callback will be called when a DALI frame is received. when a DALI frame was sent successfully or could not be sent (timeout). periodically if Periodic status transmission is not 0. Periodic status transmission [100 usec]: If not 0, the callback function will be called in the given time interval with the actual DALI interface status. This feature is used by the Framework Library. Without the Framework Library, it can be used by the application for timing purposes and may eliminate the need for additional timers. The configuration of the General Purpose Timer (GPT) module used by the Framework Driver is done in the Properties dialog of the module within e2studio. Page 8

9 Name: Name of the control variable. Channel: Channel number of the used GPT timer. Make sure to use a GPT channel that is not used for other purposes in your application. Interrupt Priority: Must be enabled. Setting it to the same priority as the four DALI interrupts of the HAL Driver is a good starting point for the application. There is no need to configure the other properties of the timer module API Usage The DALI Framework defines APIs for controlling the DALI interface and sending frames. It is very similar to the API of the HAL Driver. A complete list of the available APIs, an example API call, a short description of each and the API status return values can be found in the tables below. For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the API Reference manual for the module. Function name.open Example API Call and Definition g_sf_dali0.p_api->open(g_sf_dali0.p_ctrl, g_sf_dali0.p_cfg) This API must be called once before using the Framework Driver and the DALI interface. It will initialize and open both. Page 9

10 .close g_sf_dali0.p_api->close(g_sf_dali0.p_ctrl) This API can be called to shut down the Framework Driver and the DALI interface. It will clean-up and close both. Before the interface can be used again a call to open is necessary..write dali_frame_t frame; // declare frame variable frame.data_length=16; // send a 16 bit frame frame.data=0xa701; // data to be send frame.priority=dali_frame_priority_3; // send with priority 3 g_sf_dali0.p_api->write(g_sf_dali0.p_ctrl, &frame); This API must be called to send a DALI frame. frame must be of type dali_frame_t and filled with the necessary information..infoget.versionget dali_info_t info; // declare variable that will receive the information g_sf_dali0.p_api->infoget(g_sf_dali0.p_ctrl, &info); This API can be called to retrieve status and statistical information about the DALI interface. g_sf_dali0.p_api->versionget(&version) Retrieve the API version with the version pointer. Can be called even if the interface is not opened. Table 3: API of DALI Framework driver Each call to an API will return a status return value listed in Table Operation The configuration of the Framework Driver is normally done by setting the properties in the e2 studio. The Framework Driver is then initialized and un-initialized by calling its API open and close functions. Calling open will in turn open the associated timer and HAL Driver and make the necessary connections between them. Calling close will close the timer and HAL Driver. However, if the application uses the Library Framework, the Library Framework will call these functions when it is opened/closed. In this case it not necessary to call any Framework Driver API function from the application. The operation of the Framework Driver is the same as the operation of the HAL Driver without the need to call the.timinghelper API. Please refer to the HAL Driver description for more details. The same applies to Timing and Interrupt Context operation considerations Threads The Framework Driver does not depend on ThreadX and does not use any threads. It is mainly interrupt-driven by either the DALI interface interrupts or timer interrupts Application An application may use the Framework Driver directly without the Library Framework. This chapter gives an overview of the necessary steps and an example of how to use the Framework Driver in your own application. Including the Framework Driver in your applications Page 10

11 Make sure to have the Dali Framework pack files installed in e2studio. Then, from e2studio, open your applications configuration and add Framework Connectivity DALI2 Framework to a thread of your application. Configure the Framework Driver Configuration can be done by editing the properties of the DALI Framework from e2studio as described in chapter Initialization Call the open function of the Framework Driver API from your application. See code example below. ssp_err_t err = g_sf_dali0.p_api->open(g_sf_dali0.p_ctrl, g_sf_dali0.p_cfg); if (SSP_SUCCESS!= err) { /* TODO: add error handling */ } Receive frames and status information Frames and status information are received with the help of the provided callback function. The prototype of this function is void dali_callback(dali_frame_t * p_frame); As discussed above, the processing should be as fast as possible. It is best to do the work not in the callback function but from a thread of your application. This can be achieved by using a ThreadX message queue. Each Page 11

12 time the callback function is called it sends one message to this message queue and returns. The messages can be processed later by the application. The code example below explains this TX_QUEUE mq_dali; /* message queue for received DALI frames */ static dali_frame_t mq_dali_storage[100]; /* storage for the queue */ void dali_callback(dali_frame_t * p_frame) { /* push frame to message queue for later processing outside ISR context */ UINT err = tx_queue_send (&mq_dali, p_frame,tx_no_wait); if (TX_SUCCESS!= err) { // TODO: add error handling } } /* ThreadX application thread */ void dali_thread_entry(void) { /* Init message queue */ tx_queue_create (&mq_dali, (CHAR *) "DALI message queue", sizeof(dali_frame_t)/4+1, &mq_dali_storage, sizeof(mq_dali_storage)); } /* Init DALI Framework.*/ err=g_sf_dali0.p_api->open(g_sf_dali0.p_ctrl, g_sf_dali0.p_cfg); while (1) { ssp_err_t err; dali_frame_t frame; err = tx_queue_receive (&mq_dali, &frame, 0); if (TX_SUCCESS == err) { /* process message from DALI Framework */ } } /* send a backward telegram */ ssp_err_t send_backward_telegram(uint8_t data) { dali_frame_t frame; frame.data_length = 8; frame.data = data; frame.priority = DALI_FRANE_PRIORITY_BACKWARD; return g_sf_dali0.p_api->write( g_sf_dali0.o_ctrl, &frame); } Page 12

13 Page 13

14 3.3 Library framework: Overview and Configuration The Library Framework encapsulates the DALI Stack and the DALI Framework Driver. The Library Framework is where communication between the DALI Framework Driver and the DALI Stack is performed. This Library Framework can be used conveniently to set the configuration parameters of the DALI Stack, such as callback functions, specific manufacturer data, DALI device specifications, etc. The Library Framework makes sure that the processing of DALI Frames is not performed in the interrupt context of Framework Driver and HAL Driver. ThreadX uses a message queue for this purpose Configuration The configuration of the DALI Library Framework is done in the Properties dialog of the module within e2studio. Page 14

15 Configuration of the library framework properties Name: Name of the control variable. Stackmode: This defines the DALI device mode. Control Gear: DALI device is set up as a control gear. Control Device: DALI device is set up as a control device. Device mode: Has to be set if a control device is to be set up. Single Control device: If the device is to be the only application control device on the bus. Multi Control device: If the device is to be one of multiple application control devices on the bus. Input Control device: Input devices make a system sensitive to changes in its environment by transmitting event messages, e.g. Push Buttons Control gear device type: Has to be set if a control gear is to be set up. Two DALI control gear device types are currently supported. Fluorescent lamps (DIN ) LED modules (DIN ) Shortaddress: The short address for the DALI device. If addressing is not to be performed, 255 has to be entered. Valid value range [ ]. Callbacks: This is where callback functions are entered which have to be implemented in the application. These callback functions are called up directly by the DALI Stack. GTIN: o Ready: The application is notified by the DALI Stack that the DALI Stack has been fully initialized. o Reaction: Is called up if the application is to perform a certain action. o Load: If the persistent data is to be saved (triggered by the DALI Stack). o Save: If the persistent data is to be loaded (triggered by the DALI Stack). Global Trade Item Number, e.g., the EAN. Firmwareversion: o Firmware version (major): Valid value range [0..255]. o Firmware version (minor): Valid value range [0..255]. Page 15

16 Identifynumber: Identification number of the bus unit, preferably the serial number Hardware version: o Hardware version (major): Valid value range [0..255]. o Hardware version (minor): Valid value range [0..255]. Control Gear Parameter: The following parameters are taken into account if Control Gear is selected as Stackmode. o Physical minimum level (PHM) Physical minimum level corresponding to the minimum light output the control gear can operate at. o LED modules parameter Min. Fast Fade Time: minimum fade time. Valid value range [1..27] Gear Types Parameter Integrated Power supply: LED power supply integrated. [TRUE FALSE] Integrated LED module: LED module integrated. [TRUE FALSE] AC-Supply: AC supply possible. [TRUE FALSE] DC-Supply: DC supply possible. [TRUE FALSE] Possible Operating modes Parameter PWM-Possible: PWM mode possible. [TRUE FALSE]. AM-Possible: AM mode possible. [TRUE FALSE]. Regulated output: Output is current-controlled. [TRUE FALSE]. High current pulse: High-current pulse mode. [TRUE FALSE]. Features Parameter Short circuit: Short circuit detection can be queried. [TRUE FALSE]. Open circuit: Page 16

17 Open circuit detection can be queried. [TRUE FALSE]. Load decrease: Load decrease detection can be queried. [TRUE FALSE]. Load increase: Load increase detection can be queried. [TRUE FALSE]. Overcurrent protection: Overcurrent protection available and can be queried. [TRUE FALSE]. Thermal shutdown: Thermal shutdown can be queried. [TRUE FALSE]. Thermal overload: Lighting current reduction due to thermal overload can be queried. [TRUE FALSE]. Reference measurement: If one of the configuration parameters is set to TRUE, this parameter also has to be set to TRUE. o Load decrease o Load increase o Overcurrent protection Control Device: o Input Control Device Parameter: The following parameters are taken into account if the Input Control Device option is selected as device mode. Input device instance type: Has to be set if the Input Control Device option is selected as the device mode. Currently only one input device instance type is supported. o Push Buttons (DIN ) Input device instance number: Each instance must have a unique number in the range [0..NumberOfInstances 1]. Push Buttons Parameter: The following parameters are taken into account if the Push Buttons option is selected as input device instance type. Push button short min.: Minimum time between pressed and released. Value range in milliseconds [ ] Push button double min.: Minimum time between twice pressed. Value range in milliseconds [ ] Page 17

18 For details of the returned dalilib_cfg_t variable, see the complete DALI Stack API documentation API Usage The Library Framework defines APIs for controlling the DALI Stack receiving and sending frames. A complete list of the available APIs, an example API call, a short description of each and the API status return values can be found in the tables below. For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the DALI Stack API documentation. Function name.open.close.start.action Example API Call and Definition g_sf_dalilib.p_api->open(g_sf_dalilib.p_ctrl, g_sf_dalilib.p_cfg) This API must be called once before using the Library Framework and the DALI interface. It will initialize and open both. Create message queue for frames send to the DALI stack library. New DALI Stack instance is generated and initialized with the configuration parameters. g_sf_dalilib.p_api->close(g_sf_dalilib.p_ctrl) The connection to the DALI Framework Driver is quit, the generated DALI instance is deleted and the processing loop is quit. This API can be called to shut down the Framework Driver and the DALI interface. It will clean-up and close both. Before the interface can be used again a call to open is necessary. g_sf_dalilib.p_api->write(g_sf_dalilib.p_ctrl); Start the DALI library and process DALI frames. This function will run forever unless a severe internal error happens. If the application is to execute a DALI command actively or is to give a response to a query, this API function has to be called up. Two values have to be transferred as the parameter. Control variable (g_sf_dalilib.p_ctrll) Action-Struct (dalilib_action_t) Examples: The application executes a DALI command. The control device sets the value of the operating device to 100%. 1. dalilib_action_t action; action.actiontype = DALILIB_CTRL_GEAR_ACTION; action.gearact.adr.adr = 0x02; action.gearact.adr.adrtype = DALI_ADRTYPE_SHORT; action.gearact.gearactiontype = DALILIB_ACT_TYPE_CTRL_GEAR_LEVEL; action.gearact.value.actionvalue = (uint32_t)level * 1000; action.gearact.action.levelaction = DALILIB_ACT_CTRL_GEAR_LEVEL_DAPC; g_sf_dalilib.p_api->action(g_sf_dalilib.p_ctrl, &action); The application sends a DALI query to the control gear with the short address 0x02. The light value is queried. 1. dalilib_action_t action; Page 18

19 action.actiontype = DALILIB_CTRL_GEAR_ACTION; action.gearact.adr.adr = 0x02; action.gearact.adr.adrtype = DALI_ADRTYPE_SHORT; action.gearact.gearactiontype = DALILIB_ACT_TYPE_CTRL_GEAR_QUERIES; action.gearact.action. queriesaction = DALILIB_ACT_CTRL_GEAR_QUERY_ACTUAL_LEVEL; g_sf_dalilib.p_api->action(g_sf_dalilib.p_ctrl, &action); Control gear sends the response to the query from a control device. Three steps are executed for the response. 1. DALI Stack triggers the reaction callback function in order to learn the current light value from the application. 2. The application transfers the value to the DALI Stack with the action function. dalilib_action_t action; act.actiontype = DALILIB_CTRL_GEAR_ACTION; act.gearact.action.internalaction = DALILIB_ACT_INTERNAL_CTRL_GEAR_SET_ACTUAL_LEVEL; act.gearact.gearactiontype = DALILIB_ACT_TYPE_INTERNAL_CTRL_GEAR; act.gearact.value.actionvalue = 60; // 60% light value g_sf_dali0.p_api->action(g_sf_dali0.p_ctrl, &act); 3. DALI Stack sends the response. Please refer to the DALI Stack API documentation for more details..versionget g_sf_dalilib.p_api->versionget(&version) Retrieve the API version with the version pointer. dali_wrapper_callback This function should be entered when configuring the DALI Framework Driver as a callback parameter. This callback function is called up by the DALI Framework Driver when a DALI frame is to be forwarded to the DALI Library Framework. This function inserts the DALI frame into the ThreadX message queue. dalilib_wrapper_send This callback function is set in the open function. The application does not take care of initializing this function. API of DALI Library Framework This API function is called up by the DALI Stack when a DALI frame is to be transferred to the DALI Framework Driver Thread Overview The Library Framework requires its own thread. It uses a ThreadX message queue to transport the received DALI frames from the interrupt context of the Framework Driver to this thread context. This is performed automatically so that the application does not have to take care of different contexts. It is the job of the application to start the Library Framework in its own thread (API function: start) Page 19

20 3.3.4 Application This section describes how the module can be used in an application Including the Library Framework in an Application Make sure to have the DALI Library Framework pack files installed in e2studio. Then, from e2studio, open your applications configuration and add Framework Connectivity DALILIB2 Framework to a thread of your application. Configure the DALI Library Framework Configuration can be done by editing the properties of the DALI Library Framework from e2studio as described in chapter Initialization To initialize the DALI Library Framework, after setting the configuration parameters, the API function open first has to be called up. If the open function call-up was successful, the API function start can be used to start the DALI Library Framework. The start function is used to start the processing loop and process the incoming DALI frames in the ThreadX message queue. See code example below. Callback functions o Ready This function is called up when the DALI Framework Driver and the DALI Library Framework are finished with initializations. From now, the application can use DALI Library Framework functionalities. Page 20

21 o Load/Save If the persistent data are to be loaded from the memory or written to the memory, these functions are called up. It is the job of the application to provide persistent saving and loading of the transferred data. o Reaction This function is called up if the application is to react to a DALI command. Please refer to the DALI Stack API Documentation for more details. Page 21

22 4. Memory Usage The typical memory usage of a small application including the Library Framework, Framework Driver and the HAL Driver is shown in the image above. 5. Architecture block diagram Page 22