dali control gear library and demo application user...

2014 Microchip Technology Inc. DS40001755A

DALI Control Gear Library andDemo Application

User’s Guide

DS40001755A-page 2 2014 Microchip Technology Inc.

Information contained in this publication regarding deviceapplications and the like is provided only for your convenienceand may be superseded by updates. It is your responsibility toensure that your application meets with your specifications.MICROCHIP MAKES NO REPRESENTATIONS ORWARRANTIES OF ANY KIND WHETHER EXPRESS ORIMPLIED, WRITTEN OR ORAL, STATUTORY OROTHERWISE, RELATED TO THE INFORMATION,INCLUDING BUT NOT LIMITED TO ITS CONDITION,QUALITY, PERFORMANCE, MERCHANTABILITY ORFITNESS FOR PURPOSE. Microchip disclaims all liabilityarising from this information and its use. Use of Microchipdevices in life support and/or safety applications is entirely atthe buyer’s risk, and the buyer agrees to defend, indemnify andhold harmless Microchip from any and all damages, claims,suits, or expenses resulting from such use. No licenses areconveyed, implicitly or otherwise, under any Microchipintellectual property rights.

Note the following details of the code protection feature on Microchip devices:• Microchip products meet the specification contained in their particular Microchip Data Sheet.

• Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions.

• There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property.

• Microchip is willing to work with the customer who is concerned about the integrity of their code.

• Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as “unbreakable.”

Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of ourproducts. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such actsallow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act.

Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001:2000 certified.

QUALITY MANAGEMENT SYSTEM CERTIFIED BY DNV

== ISO/TS 16949 ==

Trademarks

The Microchip name and logo, the Microchip logo, dsPIC, FlashFlex, KEELOQ, KEELOQ logo, MPLAB, PIC, PICmicro, PICSTART, PIC32 logo, rfPIC, SST, SST Logo, SuperFlash and UNI/O are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries.

FilterLab, Hampshire, HI-TECH C, Linear Active Thermistor, MTP, SEEVAL and The Embedded Control Solutions Company are registered trademarks of Microchip Technology Incorporated in the U.S.A.

Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries.

Analog-for-the-Digital Age, Application Maestro, BodyCom, chipKIT, chipKIT logo, CodeGuard, dsPICDEM, dsPICDEM.net, dsPICworks, dsSPEAK, ECAN, ECONOMONITOR, FanSense, HI-TIDE, In-Circuit Serial Programming, ICSP, Mindi, MiWi, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, mTouch, Omniscient Code Generation, PICC, PICC-18, PICDEM, PICDEM.net, PICkit, PICtail, REAL ICE, rfLAB, Select Mode, SQI, Serial Quad I/O, Total Endurance, TSHARC, UniWinDriver, WiperLock, ZENA and Z-Scale are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries.

SQTP is a service mark of Microchip Technology Incorporated in the U.S.A.

GestIC and ULPP are registered trademarks of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of Microchip Technology Inc., in other countries.

All other trademarks mentioned herein are property of their respective companies.

© 2014, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved.

Printed on recycled paper.

ISBN: 978-1-63276-265-8

DALI CONTROL GEAR LIBRARY AND
DEMO APPLICATION USER’S GUIDE
Table of Contents

Preface ........................................................................................................................... 5Introduction............................................................................................................ 5Document Layout .................................................................................................. 5Conventions Used in this Guide ............................................................................ 6Recommended Reading........................................................................................ 7The Microchip Web Site ........................................................................................ 7Customer Support ................................................................................................. 8Document Revision History ................................................................................... 8

Chapter 1. Overview1.1 Introduction ..................................................................................................... 91.2 DALI Control Gear Hardware ....................................................................... 10

1.2.1 Microcontroller Clock Source ..................................................................... 101.2.2 User Interface ............................................................................................ 10

1.3 DALI Requirements ...................................................................................... 111.3.1 Generating DALI Bit Timings ..................................................................... 111.3.2 Nonvolatile Memory ................................................................................... 11

Chapter 2. DALI Control Gear Library2.1 Hardware Requirements .............................................................................. 132.2 Specifications ............................................................................................... 13

2.2.1 DALI Control Gear Library Limitations ....................................................... 13

2.3 Structure ....................................................................................................... 142.4 DALI Control Gear Library Implementation Details ...................................... 16

2.4.1 Hardware Abstraction Layer ...................................................................... 162.4.2 DALI Protocol ............................................................................................ 162.4.3 DALI Machine ............................................................................................ 17

2.5 Configuring the library .................................................................................. 172.5.1 Device Type 6 Compatibility ...................................................................... 172.5.2 Non-Mandatory Memory Bank Implementation ......................................... 182.5.3 Physical Minimum Level ............................................................................ 182.5.4 Special Fade Time for DAPC Sequence ................................................... 182.5.5 Additional values for Device Type 6 Devices ............................................ 19

Chapter 3. DALI Control Gear Application Example3.1 Introduction ................................................................................................... 203.2 DALI Control Gear Application Initialization ................................................. 203.3 Application Structure and Data Flow ............................................................ 22

2014 Microchip Technology Inc. DS40001755A-page 3

DALI Control Gear Library and Demo Application User’s Guide

Appendix A. DALI Control Gear Library API A.1 Introduction .................................................................................................. 24

Worldwide Sales and Service .....................................................................................27


Preface

INTRODUCTIONThis chapter contains general information that describes the DALI Control Gear Library as well as the DALI Control Gear demo application. Items discussed in this chapter include:• Document Layout• Conventions Used in this Guide• Recommended Reading• The Microchip Web Site• Customer Support• Document Revision History

DOCUMENT LAYOUTThis document describes the structure and the interface of the DALI Control Gear Library as well as the DALI Control Gear demo application. The demo application can easily be modified to be adapted to different hardware.This document covers a detailed description of the application and the library. More information can be found within the source code of the project. The manual layout is as follows:• Chapter 1. “Overview”• Chapter 2. “DALI Control Gear Library”• Chapter 3. “DALI Control Gear Application Example”• Appendix A. “DALI Control Gear Library API”

NOTICE TO CUSTOMERS

All documentation becomes dated, and this manual is no exception. Microchip tools and documentation are constantly evolving to meet customer needs, so some actual dialogs and/or tool descriptions may differ from those in this document. Please refer to our web site (www.microchip.com) to obtain the latest documentation available.

Documents are identified with a “DS” number. This number is located on the bottom of each page, in front of the page number. The numbering convention for the DS number is “DSXXXXXA”, where “XXXXX” is the document number and “A” is the revision level of the document.

For the most up-to-date information on development tools, see the MPLAB IDE online help. Select the Help menu, and then Topics to open a list of available online help files.



CONVENTIONS USED IN THIS GUIDEThis manual uses the following documentation conventions:

DOCUMENTATION CONVENTIONSDescription Represents Examples

Arial font:Italic characters Referenced books MPLAB® IDE User’s Guide

Emphasized text ...is the only compiler...Initial caps A window the Output window

A dialog the Settings dialogA menu selection select Enable Programmer

Quotes A field name in a window or dialog

“Save project before build”

Underlined, italic text with right angle bracket

A menu path File>Save

Bold characters A dialog button Click OKA tab Click the Power tab

N‘Rnnnn A number in verilog format, where N is the total number of digits, R is the radix and n is a digit.

4‘b0010, 2‘hF1

Text in angle brackets < > A key on the keyboard Press <Enter>, <F1>Courier New font:Plain Courier New Sample source code #define START

Filenames autoexec.bat

File paths c:\mcc18\h

Keywords _asm, _endasm, static

Command-line options -Opa+, -Opa-

Bit values 0, 1

Constants 0xFF, ‘A’

Italic Courier New A variable argument file.o, where file can be any valid filename

Square brackets [ ] Optional arguments mcc18 [options] file [options]

Curly brackets and pipe character: { | }

Choice of mutually exclusive arguments; an OR selection

errorlevel {0|1}

Ellipses... Replaces repeated text var_name [, var_name...]

Represents code supplied by user

void main (void){ ...}


Preface

RECOMMENDED READINGThis user’s guide describes the structure and the interface of the DALI Control Gear Library as well as the DALI Control Gear demo application. Other useful documents are listed below. The following Microchip documents are available and recommended as supplemental reference resources.Read me FilesFor the latest information on using other tools, read the tool-specific Readme files in the Readmes subdirectory of the MPLAB® X IDE installation directory. The Readme files contain update information and known issues that may not be included in this user’s guide.• IEC 62386-102 General Requirements – Control Gear: This document

describes the protocol and methods for testing of DALI devices.• IEC 62386-207 Particular Requirements for Control Gear – LED Modules

(Device Type 6): This document establishes the specific requirements for LED modules (device type 6).

• Microchip DS40001414: The data sheet for the PIC16F1947 microcontroller which is used in this demo application.

• Microchip Lighting Resources: http://www.microchip.com/lighting• DALI AG web site: http://www.dali-ag.org/

THE MICROCHIP WEB SITEMicrochip provides online support via our web site at www.microchip.com. This web site is used as a means to make files and information easily available to customers. Accessible by using your favorite Internet browser, the web site contains the following information:• Product Support – Data sheets and errata, application notes and sample

programs, design resources, user’s guides and hardware support documents, latest software releases and archived software

• General Technical Support – Frequently Asked Questions (FAQs), technical support requests, online discussion groups, Microchip consultant program member listing

• Business of Microchip – Product selector and ordering guides, latest Microchip press releases, listing of seminars and events, listings of Microchip sales offices, distributors and factory representatives


http://www.microchip.com/lighting

http://www.dali-ag.org/


CUSTOMER SUPPORTUsers of Microchip products can receive assistance through several channels:• Distributor or Representative• Local Sales Office• Field Application Engineer (FAE)• Technical SupportCustomers should contact their distributor, representative or field application engineer (FAE) for support. Local sales offices are also available to help customers. A listing of sales offices and locations is included in the back of this document.Technical support is available through the web site at: http://support.microchip.com

DOCUMENT REVISION HISTORY

Revision A (June 2014)• Initial release of this document.


DALI CONTROL GEAR LIBRARY ANDDEMO APPLICATION USER’S GUIDE

Chapter 1. Overview

1.1 INTRODUCTIONThe DALI Control Gear demo application that relies on the DALI Control Gear Library is designed to run on the Microchip Lighting Communication Main Board (DM160214, see Figure 1-1) with the Microchip DALI Adapter (AC160214-1, see Figure 1-2).

FIGURE 1-1: LIGHTING COMMUNICATION MAIN BOARD

FIGURE 1-2: DALI ADAPTER



1.2 DALI CONTROL GEAR HARDWAREThe Microchip Lighting Communications Main Board’s hardware consists of an 8-bit Microchip microcontroller (PIC16F1947), power supply, a current-controlled RGBW LED, an interface port and the user interface elements: a slider, four push buttons and an LCD.The Microchip DALI Adapter, which attaches to the main board’s interface port, provides the needed circuitry for interfacing to a DALI bus. The current library and demo application only targets LED modules (Device Type 6), which do not support multiple color channels. Thus, the application uses just the white die available in the RGBW LED package.

1.2.1 Microcontroller Clock SourceThe application uses the microcontroller’s internal oscillator, configured for 8 MHz and the on-chip 4xPLL, to achieve a system clock of 32 MHz. Although an 8 MHz crystal is available on the Lighting Communications Main Board, the internal oscillator has been used since the DALI bus does not have very strict timing constraints.

1.2.2 User InterfaceSince the hardware cannot perform all the measurements required by a fully-featured DALI compliant device, some of the measurements are simulated using button combinations on the Lighting Communications Main Board. In order to keep the application minimal, the on-board LCD and slider on the DALI Control Gear remain unused.The measurements that are simulated can indicate the following Fault conditions. Please note that since switches S2 and S3 perform different functions when used alone or when in combination with S4 or S5, the order in which combinations are pressed is relevant. To simulate “Load Increase” (S5 + S2), first press S5 and then, keeping S5 pressed, also press S2.

TABLE 1-1: SIMULATING FAULT CONDITIONSPressed Switches Simulated Fault Condition

S2 Open Circuit (Lamp disconnected)S3 Short CircuitS4+S2 Thermal OverloadS4+S3 Thermal ShutdownS5+S2 Load IncreaseS5+S3 Load DecreaseS5+S4 Disturb reference system power


Overview

1.3 DALI REQUIREMENTS

1.3.1 Generating DALI Bit TimingsThe DALI protocol consists of a Manchester encoded signal at 1200 bps, which defines the half-bit time of 416.6(7) µs. To achieve this DALI half-bit time (TE) of 416.67 µs, Timer1 is used with its clock source set to FOSC/4 and prescaler 1:4. In this case, the timer incrementing frequency will be 2 MHz. Since an important value that will need to be used is the number of timer ticks that make up a TE, we can find out that:

EQUATION 1-1: RELATIONSHIP BETWEEN TIMER FREQUENCY AND DALI HALF-BIT PERIOD (TE)

The symbol TE is defined in ‘dali_cg_hardware.h’ to have this value, as it is used throughout the library. Since Timer1 is a 16-bit timer, it has no problem accommodating this value.

1.3.2 Nonvolatile MemoryThe library requires some nonvolatile storage in order to implement the following:• Some DALI variables such as short address, fade times, power-on level, etc.• Most recent power level used. When configured to do so, the Control Gear needs

to be able to retrieve at power-up the most recent power level used• Memory in DALI memory banks• Although strictly not part of the library, the reference system power measurement

also needs to store its result(s) to nonvolatile memoryThe number of bytes the library requires for the DALI variables needed to be stored in nonvolatile memory is accessible using the DALI_MACHINE_NVMEMORY_REQUIRED symbol defined in ‘dali_cg_machine.h’. How memory is implemented in hardware is irrelevant to the library, as the application will access it through calls to nvmem_daliReadByte(location) and nvmem_daliWriteByte(location, value) which need to be implemented in ‘dali_cg_nvmemory.c’ along with other functions. The parameter “location” can take any value from “0” to “DALI_MACHINE_NVMEMORY_REQUIRED - 1”.

2 MHz 416.67s 833 Timer ticks

Note: The application will need to also accommodate (within the allowed range of the timer used) values as large as 15 * TE, thus placing boundaries on the timer’s clocking sources.



The most recent power level used needs to be stored under certain control gear configurations. Since this value may be updated often, excessive wear of the nonvolatile medium can occur. In order to allow the application to mitigate this, a dedicated pair of functions is used to implement the storage/retrieval of this value (nvmem_daliWriteLastLevel(level) and nvmem_daliReadLastLevel()). As an example of lowering the wear of the nonvolatile memory, the demo application uses a 16-byte circular buffer in the internal EEPROM in order to reduce the usage of each individual EEPROM cell. The PIC16F1947 has a large amount of data memory and could accommodate even larger circular buffers for the task.

The DALI standard defines memory banks that should be implemented in the control gear and which can be accessed remotely, via the DALI bus. The only mandatory memory bank is Bank 0; the library allows the definition and use of up to eight memory banks; however memory Bank 0 can only be a read-only one. The implementation of the memory banks is irrelevant to the library, as it accesses them through nvmem_daliBankMemoryRead(bank, location) and nvmem_daliBankMemoryWrite(bank, location, value). The access mechanism required by IEC 62386-102 (using the write-enabled state and the lock bytes for each bank) is handled by the DALI Control Gear Library.

Note: Other implementations could work even better, for example, the application can use regular RAM for all nonvolatile requirements if the application can detect an imminent power failure. Then the RAM would be copied over to nonvolatile memory only in case of such an imminent power failure.


Chapter 2. DALI Control Gear Library

2.1 HARDWARE REQUIREMENTS• One External interrupt which functions as the receiver pin for the DALI Interface• One GPIO pin which functions as the transmitter pin for the DALI Interface• One Timer which is used to generate the DALI waveforms when transmitting and

to check the waveforms when receiving• 1 ms tick that needs to be provided by the application• Lamp control mechanism• Nonvolatile memory storage• Reference system power (optional)

2.2 SPECIFICATIONSThe DALI Control Gear Library handles:• Communication on the DALI bus (reception of forward frames, transmission of

backward frames and detection of communication, timing or bus disconnection errors)

• DALI specific variables, both RAM-based as well as nonvolatile ones• Checking if received forward frames are addressed to the current control device• Interpretation of DALI commands and procedures• Fading with the requested fade rates or fade times• Special answers on the DALI bus at different Fault conditions• Memory bank access control (implementing memory locks for writable memory,

memory bank checksums)

2.2.1 DALI Control Gear Library LimitationsThe DALI Control Gear Library does not handle any of the following aspects, since these depend on the specific application, the lamp characteristics and the available hardware:• Lamp dimming: While the DALI Control Gear Library tells the application how

bright the lamp should be, it is the application layer that needs to drive the lamp power to that level, taking into account the lamp characteristics.

• Turning the lamp off or reducing the power output in case of Fault conditions: The library does reply that the lamp is off when required by the standard, but it does not command the application to turn it off. This should be handled by the application based on lamp hardware implementation.

• Lamp status: The DALI Control Gear Library needs to be aware of the status of the lamp and the application needs to use the API to periodically update this lamp status within the application. This should be handled by the application based on lamp hardware implementation.

• Nonvolatile memory: The DALI Control Gear Library uses a number of functions that need to interface to the nonvolatile memory. This is handled by the application layer.



• Reference system power: The DALI Control Gear Library implements the control mechanism for starting/stopping/querying the reference system power measurement, but it is the application which needs to implement it.

2.3 STRUCTUREThe DALI Control Gear Library is schematically presented in Figure 2-1, along with the application since the application needs to provide quite an extensive interface to the hardware and the library cannot be completely described out of context.The DALI Control Gear application is layered and modular, built around the core of the library, implemented in ‘dali_cg_layer’, ‘dali_cg_machine’ and ‘dali_cg_protocol’. Below is a brief description of each layer:• main – The application loop keeps the DALI Control Gear Library and the lamp

control mechanism synchronized, and also calls ‘dali_tasks()’ to run the DALI machine. The Interrupt Service Routine branches to the appropriate functions within the DALI system (1 ms tick, External interrupt and TE Timer interrupt)

• dali_cg_layer - provides the API to the library. It is implemented as a buffer between the core of the library and the user application

• dali_cg_machine - is the core of the DALI command processing system• dali_cg_protocol - implements transmission, reception of data and error

detection on the DALI bus• dali_cg_hardware - is a hardware abstraction layer that allows users to

easily port the library to other PIC® microcontrollersAlthough not an integral part of the library, required functionality needs to be provided by the following functional blocks:• random - provides random number generation that is needed during DALI

commissioning• dali_cg_nvmemory - implements the application-specific nonvolatile memory

management.

The lighting hardware is grouped in two more functional blocks:• lamp_hardware - implements the lamp management functionality, such as

setting power levels using the required dimming curve and also provides data for the lamp status

• lamp_reference_system_power - groups functionality required by the implementation of any reference system power measurement

Note: Implementing the reference system power measurement and the lamp status information are optional; please check IEC 62386-102 and IEC 62386-207 for further details.

Note: Some of the functions this block provides need to adhere to some restrictions since these are called from the core of the DALI Control Gear Library.


DA

LI Control G

ear Library

2014 M

icrochip Technology Inc.D

S40001755A

-page 15

FIG

ISR()

dali_interruptTeTimer()

idali_receiveForwardFrame() e data

Ext. Interrupt Timer

dali_tick1ms()

idali_tick1msMachine()

1ms tick

DALI Communication

dali_interruptExternal()

Timer GPIO

LampStatus()

ampPower()

ampOperatingMode()

s and Control tIdentificationProcedure()

URE 2-1: DALI CONTROL GEAR DEMO APPLICATION ARCHITECTURE

main

dali_cg_layer

dali_cg_hardware

dali_cg_machine

dali_cg_protocol

while(1) { dali_tasks(); lamp_setPower(dali_getPower()); dali_setStatus(lamp_getStatus()); }

dali_tasks() fram

MCU Hardware

idali_startReferenceSystemPower()

idali_stopReferenceSystemPower()

idali_getStatusReferenceSystemPower()

Reference System Power

Timer

idali_get

idali_setL

idali_getL

Lamp Statuidali_star

idali_sendBackwardFrame()

dali_tasks() Code Function call

Shared data Functionality group

Hardware configuration Hardware Feedback/readout

DALI Control Gear stack and application

lamp_reference_system_power

dali_cg_nvmemory

lamp_hardware

CCP

LED Dimming

GPIO

Buttons

nvmem_daliReadByte()

nvmem_daliWriteByte()

nvmem_daliWriteLastLevel()

nvmem_daliReadLastLevel()

Non-Volatile Memory

nvmem_daliBankMemoryRead()

nvmem_daliBankMemoryWrite()

Bank Memory

dali_getPower()

dali_setStatus()

lamp_getStatus()

lamp_setPower()

dali_setReferenceSystemPowerStatus()

lampRefSysPower_start()

lampRefSysPower_getStatus()

nvmem_refSysPowerReadByte() nvmem_refSysPowerWriteByte()


random

random_byte()

dali_getFlags()

EEPROM

NV Memory

GPIO

Buttons

dalihw_isDALILineLow()

dali_setOperatingMode()

lamp_getOperatingMode()

lampRefSysPower_stop()

lampRefSysPower_tick1ms()


2.4 DALI CONTROL GEAR LIBRARY IMPLEMENTATION DETAILSThis section gives details on the different layers of the library. For further information, please check the comments in the relevant source code files.

2.4.1 Hardware Abstraction LayerThe library depends heavily on a small number of peripherals to implement the DALI protocol. In order to make it as portable as possible, the hardware interface is separated from the rest of the code. The flexibility provided by this layer, along with the small number of peripherals should allow for seamless adaptation of the library to new architectures.

2.4.2 DALI ProtocolThe DALI Control Gear Library does not use any specific hardware to implement its communication layer (Manchester decoding/encoding), in order to be easily portable to most Microchip PIC microcontrollers. The library uses a state machine driven by the external interrupt and a timer for both reception and transmission of bits using the DALI bus, as well as for bit and framing error detection and making sure the inter-frame timings defined by IEC 62386-102 are respected. This communication layer is isolated in its own file having a simple interface to ‘dali_cg_machine’. If necessary, it can easily be replaced by a hardware-optimized version.While no data transfer is taking place, the protocol state machine keeps the external interrupt on the receive pin armed. Once this interrupt is triggered, the timer in conjunction with this external interrupt are used both for checking the correct format of the bits that are being received as well as for detecting a time-out which would signal an error.Figure 2-2 shows the waveform corresponding to the command “BROADCAST DIRECT ARC POWER CONTROL 58”, where the individual bit times (2 TE) are delimited by dotted lines.

FIGURE 2-2: WAVEFORM ON THE DALI BUS THAT TRANSMITS THE ‘BROADCAST DIRECT ARC POWER CONTROL 58’ COMMAND


DALI Control Gear Library

The library checks for the correct timings for the pulses and Stop bits and discards the frame if it is found to be malformed. The acceptable timings for valid pulse widths within a frame (1 TE or 2 TE) are derived from the TE value which is set in the demo application to 416.5 µs. The received pulse width is checked against the following values:• 1 TE if pulse width in [208.25 µs, 541.45 µs]• 2 TE if pulse width in [583.1 µs, 1082.9 µs].When required to transmit data, the library generates the bit timings using the same timer.

2.4.3 DALI MachineThe core of the DALI Control Gear Library has three main entry points after initialization:• Forward frame reception (from the protocol layer, called from the

interrupt). Since the interrupt routine is rather lengthy (it has to decode/encode the Manchester signal), the data received from the bus is stored during forward frame reception in a variable and is accessed by the state machine’s run function whenever it is run by the mainline code.

• 1 ms tick (from the interrupt) which is required by the fading mechanism and by various software timers that the DALI standard requires to be implemented (such as the time between cable disconnection and going to the system failure level if it’s programmed to do so).

• State machine run function, ‘dali_tasks()’, called as often as possible by its main application loop. This function processes any new data received from the bus, checks the system parameters and updates its internal flags accordingly.

Apart from these, the library exposes a number of functions which need to be used to update the library’s copies of lamp status variables and to provide the library commands that the application should execute.This state machine also implements the DALI specific mechanisms, such as handling the commissioning process, nonvolatile memory access, etc.

2.5 CONFIGURING THE LIBRARYParameters for the DALI Control Gear Library are placed in ‘dali/dali_cg_config.h’. The DALI Control Gear Library can have some of its functionality enabled or disabled according to the user requirements. Disabling some functionality removes some of the code, thus resulting in a smaller binary. The features that can be disabled are:• Device Type 6 (LED) compatibility• Non-mandatory memory bank implementation

2.5.1 Device Type 6 CompatibilityThe DALI standard defines multiple device types, of which type number six represents LED lamps. Supporting a specific device type requires device special commands to be implemented. Device Type 6 compatibility is enabled by defining the symbol:’DALI_USE_DEVICE_TYPE_6’.

Note: The Control Gear needs to support at least one device type, thus this may require library modifications in order to remain DALI compliant.



2.5.2 Non-Mandatory Memory Bank ImplementationThe DALI documentation defines memory banks that can be accessed remotely by the control device. The DALI Control Gear Library implements Bank 0 as a read-only bank, which is required by the standard irrespective of this setting. Enabling this setting allows the user to implement other banks which can also be written. Implementing these banks can be done by the user in the nonvolatile memory layer. This functionality is enabled by defining the symbol ‘DALI_USE_EXTRA_MEMORY_BANKS’.

2.5.3 Physical Minimum LevelThe ‘PHYSICAL_MINIMUM_LEVEL’ symbol is the minimum output power that the lamp can produce and should hold a value between 1 and 254 (inclusive). Details on the physical minimum level can be found in IEC 62386-102.

2.5.4 Special Fade Time for DAPC SequenceDuring a DAPC sequence, the programmed fade time shall be replaced by a special fade time, greater than or equal to 200 ms. The DAPC_SEQUENCE_FADE_TIME_MS symbol defines that special fade time. Although this value is expressed in milliseconds, within the library it has a granularity of 5 ms.Details on the DAPC sequence mechanism can be found in IEC 62386-102, section 11.1.2, Command 9.

Note: The DALI memory banks are not related to the Microchip PIC device mem-ory banks. The former are described in detail in IEC 62386-102, section 9.8, whereas the latter in the microcontroller’s data sheets.

Note: A non-dimmable DALI device can be built by setting ‘PHYSICAL_MINIMUM_LEVEL’ to 254.


DALI Control Gear Library

2.5.5 Additional values for Device Type 6 DevicesIf Device Type 6 compatibility is required, four more values need to be defined:• GEAR_TYPE: Control Gear parameters. Please see IEC 62386-207,

section 11.3.4.2, Command 237 for further details.• MIN_FAST_FADE_TIME: Please see IEC 62386-207, section 9.13 for

details on the fast fade time. The valid range for this value is between 1 and 27 (inclusive).

• POSSIBLE_OPERATING_MODES: Please see IEC 62386-207, section 11.3.4.2, Command 239 for further details on operating modes.

• FEATURES: Please see IEC 62386-207, section 11.3.4.2, Command 240 for further details on operating the FEATURES byte.

Note: GEAR_TYPE, POSSIBLE_OPERATING_MODES and FEATURES parameters should reflect the functionality implemented by the application, as no checks are made by the library in this respect.


Chapter 3. DALI Control Gear Application Example

3.1 INTRODUCTIONThe provided API places the DALI Control Gear Library under the control of the application. The user application needs to make sure that the values in the library are updated periodically, by calling the appropriate functions often. Similarly, the application should check if the lamp power needs to be updated and do so. Minimum update rate should be fast enough to keep up with lamp fade characteristics.

3.2 DALI CONTROL GEAR APPLICATION INITIALIZATIONThe library initialization resets the internal state machines. The application hardware has a separate initializer such that the user can choose to merge this with the rest of the application’s hardware initialization. In the case of the demo application, the initialization calls are shown in Example 3-1.

EXAMPLE 3-1: INITIALIZATION CALLS FOR THE DEMO APPLICATION// define a variable of flags that will be used to obtain status from the library

tdali_flags_cg daliCGFlags;

// clear all flags

daliCGFlags.All = 0;

// code that configures the system clock

[...]

// code that configures a timer to generate a 1ms tick

[...]

// not part of the library, initialize random number generator

random_init();

// initialise DALI communication hardware

dalihw_init();

// not part of the library, initialize lamp hardware

lamp_init();

// not part of the library, initialise lamp reference system power

lampRefSysPower_init();

// obtain physical minimum level for the non-logarithmic dimming curve such that

// the library can align the two minima

dali_setNonLogPhysicalMinimum(lamp_getDimmingTableValue(PHYSICAL_MINIMUM_LEVEL));

// initialise DALI library

dali_init();

// enable interrupts

ei();

while(1)

{

[...]

}


DA

LI Control G

ear Library and Dem

o Application U

ser’s Guide

2014 M

icrochip Technology Inc.D

S40001755A

-page 21

ION

ocol

ISR()

dali_interruptTeTimer()

idali_receiveForwardFrame() frame data

Ext. Interrupt Timer

dali_tick1ms()

idali_tick1msMachine()

1ms tick

DALI Communication

dali_interruptExternal()

Timer GPIO

idali_getLampStatus()

idali_setLampPower()

idali_getLampOperatingMode()

mp Status and Control idali_startIdentificationProcedure()

ame()

FIGURE 3-1: LAMP DIMMING AND LAMP STATUS DATA FLOW THROUGH THE DALI APPLICAT

main

dali_cg_layer

dali_cg_hardware

dali_cg_machine

dali_cg_prot

while(1) { dali_tasks(); lamp_setPower(dali_getPower()); dali_setStatus(lamp_getStatus()); }

dali_tasks()

MCU Hardware

idali_startReferenceSystemPower()

idali_stopReferenceSystemPower()

idali_getStatusReferenceSystemPower()


Timer

La

idali_sendBackwardFr

dali_tasks() Code Function call

Shared data Functionality group

Hardware configuration Hardware Feedback/readout

DALI Control Gear stack and application

lamp_reference_system_power

dali_cg_nvmemory

lamp_hardware

CCP

LED Dimming

GPIO

Buttons

nvmem_daliReadByte()

nvmem_daliWriteByte()

nvmem_daliWriteLastLevel()

nvmem_daliReadLastLevel()

Non-Volatile Memory

nvmem_daliBankMemoryRead()

nvmem_daliBankMemoryWrite()

Bank Memory

dali_getPower()

dali_setStatus()

lamp_getStatus()

lamp_setPower()

dali_setReferenceSystemPowerStatus()

lampRefSysPower_start()

lampRefSysPower_getStatus()

nvmem_refSysPowerReadByte() nvmem_refSysPowerWriteByte()


random

random_byte()

dali_getFlags()

EEPROM

NV Memory

GPIO

Buttons

dalihw_isDALILineLow()

dali_setOperatingMode()

lamp_getOperatingMode()

lampRefSysPower_stop()

lampRefSysPower_tick1ms()

Library obtains lamp status Library sets lamp power


DS

3.3 APPLICATION STRUCTURE AND DATA FLOWThe application structure presented earlier in Figure 2-1 is also visible in Figure 3-1, with two added lines that emphasize the data flow for the lamp power (red) from the DALI Control Gear Library to the lamp hardware and the lamp status (blue) the other way around.All data transfers are handled by the main program loop, such that the user is in total control of both library and lamp hardware. The main loop should periodically query the library flags as these carry important information regarding lamp actions that may need to be taken.During the application execution there are two entry points into the library, the main loop and the interrupts. The main loop is outlined below and keeps polling the library for work and does it if required while also continuously informing the library of the lamp status. The interrupts handle DALI bus communication and the 1 millisecond tick.

EXAMPLE 3-2: MAIN APPLICATION LOOP, HANDLING THE COMMUNICATION TO THE DALI LIBRARY

while(1)

{

// run the DALI state machine

dali_tasks();

// ask the library if it wants us to do any work

daliCGFlags.All |= dali_getFlags();

// tell the library the lamp status

dali_setStatus(lamp_getStatus());

// if the library wants us to start the identification procedure, do it

// and clear the associated flag

if (daliCGFlags.startIdentificationProcedure == 1)

{

lamp_setPower(254, 0);

daliCGFlags.startIdentificationProcedure = 0;

}

// if the library wants us to update the lamp power, do it and clear the

// flags

if (daliCGFlags.updatedLampPower == 1)

{

lamp_setPower(dali_getPower(), daliCGFlags.nonLogDimming);

daliCGFlags.updatedLampPower = 0;

daliCGFlags.nonLogDimming = 0;

}

// tell the library the lamp operating mode

dali_setOperatingMode(lamp_getOperatingMode());

// tell the library the lamp’s reference system power status

dali_setReferenceSystemPowerStatus(lampRefSysPower_getStatus());

// if the library wants us to start a reference system power do it and

// clear the flag

if (daliCGFlags.startReferenceSystemPower == 1)

{

lampRefSysPower_start();

daliCGFlags.startReferenceSystemPower = 0;

40001755A-page 22 2014 Microchip Technology Inc.

DALI Control Gear Application Example

EXAMPLE 3-3: MAIN APPLICATION LOOP, HANDLING THE COMMUNICATION TO THE DALI LIBRARY (CONTINUED)

The demo application uses a PIC16F1947 which has a single interrupt vector. Different interrupt sources are handled by checking within the interrupt code for the signal that triggered it. Below is the code that handles the three interrupts needed in the demo application. The 1 ms tick is needed by the DALI application for time-keeping reasons (and is also used by the reference system power mechanism for the same purpose). The external interrupt and TE Timer interrupt handle communication on the DALI bus.

EXAMPLE 3-4: INTERRUPT SERVICE ROUTINE FOR THE DALI COMMUNICATION AND 1 MS TICK

}

// if the library wants us to stop any running reference system power

// do that and clear the flag

if (daliCGFlags.stopReferenceSystemPower == 1)

{

lampRefSysPower_stop();

daliCGFlags.stopReferenceSystemPower = 0;

}

// check if one millisecond has passed. If so, run the corresponding

// tick function for the reference system power and clear the flag

if (daliCGFlags.tick1ms == 1)

{

lampRefSysPower_tick1ms();

daliCGFlags.tick1ms = 0;

}

}

void interrupt ISR()

{

// 1ms tick interrupt. This application uses Timer 4 for this reason.

// The lack of abstraction for this timer is due to the fact that

// it is only initialised once in main() and used once, here

if ((TMR4IF != 0) && (TMR4IE != 0))

{

TMR4IF = 0;

dali_tick1ms();

}

// Te Timer interrupt. The Te Timer is fully abstracted since it is

// heavily used within the library

if (dalihw_teTimerInterruptTriggered())

{

dalihw_teTimerClearInterrupt();

dali_interruptTeTimer();

}

// External interrupt

if ((INTF != 0) && (INTE != 0))

{

INTF = 0;

dali_interruptExternal();

}

}


DALI CONTROL GEAR LIBRARY ANDDEMO APPLICATION USER’S GUIDE

Appendix A. DALI Control Gear Library API

A.1 INTRODUCTIONBelow is a brief description of the functions that the DALI Control Gear Library provides. These are available after the inclusion of ‘dali_cg.h’.

TABLE A-1: API FUNCTIONS AND CODE EXAMPLES FOR THE DALI CONTROL GEAR LIBRARYDeclaration and Description Code example

void dalihw_init ()

DALI communication hardware configuration.dalihw_init(); // Initialise the hardware (Te // Timer, External interrupt, // pin tristate and latch // registers)

void dalihw_teTimerClearInterrupt ()

Clear TE Timer interrupt flag.void interrupt ISR(){ [...] if (dalihw_teTimerInterruptTriggered()) { dalihw_teTimerClearInterrupt(); dali_interruptTeTimer(); } [...]}

uint8_t dalihw_teTimerInterruptTriggered ()

Check if the TE Timer interrupt triggered. void interrupt ISR(){ [...] if (dalihw_teTimerInterruptTriggered()) { dalihw_teTimerClearInterrupt(); dali_interruptTeTimer(); } [...]}

void dali_interruptTeTimer ()API Call: The application should call this function for every TE Timer interrupt.

void interrupt ISR(){ [...] if (dalihw_teTimerInterruptTriggered()) { dalihw_teTimerClearInterrupt(); dali_interruptTeTimer(); } [...]}

void dali_interruptExternal ()API Call: The application should call this function for every external interrupt.

void interrupt ISR(){ [...] if ((INTF != 0) && (INTE != 0)) { INTF = 0; dali_interruptExternal(); } [...]}

void dali_init ()API Call: Initialise the DALI library

dali_init(); // Initialise DALI Library

void dali_tasks ()API Call: Run one iteration of the DALI state machine which, among others, checks if any new DALI frame has arrived and if so, processes it

while(1){ dali_tasks(); // Call DALI Library code [...] // Handle other application // aspects}

void dali_tick1ms ()API Call: Library code that should be run every millisecond

void interrupt ISR(){ if ((TMR4IF != 0) && (TMR4IE != 0)) { TMR4IF = 0; dali_tick1ms(); }}


DALI Control Gear Library API

uint8_t dali_getFlags ()

API Call: Obtain the DALI library flagsdaliCGFlags.All |= dali_getFlags();

[...] // Check flags and clear them after usage

uint8_t dali_getPower ()API Call: Obtain the power that the application should command the lamp to go to

if (daliCGFlags.updatedLampPower == 1){ lamp_setPower(dali_getPower(), daliCGFlags.nonLogDimming); daliCGFlags.updatedLampPower = 0; daliCGFlags.nonLogDimming = 0;}

void dali_setStatus (uint8_t status)API Call: Inform the library of the lamp status

// Obtain the status from the lamp and send// it to the librarydali_setStatus(lamp_getStatus());

void dali_setOperatingMode (uint8_t mode)API Call: Inform the library of the lamp operating mode

// Obtain the lamp operating mode and send it // to the librarydali_setOperatingMode(lamp_getOperatingMode());

void dali_setNonLogPhysicalMinimum (uint8_t

level)API Call: Inform the library of the non-logarithmic physical minimum level

// During initialisation, pass the// non-logarithmic value of the physical// minimum level to the librarydali_setNonLogPhysicalMinimum( lamp_getDimmingTableValue( PHYSICAL_MINIMUM_LEVEL));

void dali_setReferenceSystemPowerStatus

(uint8_t status)API Call: Inform the library of the reference system power status

// Obtain the status of the reference system// power and send it to the librarydali_setReferenceSystemPowerStatus( lampRefSysPower_getStatus());

TABLE A-1: API FUNCTIONS AND CODE EXAMPLES FOR THE DALI CONTROL GEAR LIBRARYDeclaration and Description Code example



NOTES:



AMERICASCorporate Office2355 West Chandler Blvd.Chandler, AZ 85224-6199Tel: 480-792-7200 Fax: 480-792-7277Technical Support: http://www.microchip.com/supportWeb Address: www.microchip.comAtlantaDuluth, GA Tel: 678-957-9614 Fax: 678-957-1455Austin, TXTel: 512-257-3370 BostonWestborough, MA Tel: 774-760-0087 Fax: 774-760-0088ChicagoItasca, IL Tel: 630-285-0071 Fax: 630-285-0075ClevelandIndependence, OH Tel: 216-447-0464 Fax: 216-447-0643DallasAddison, TX Tel: 972-818-7423 Fax: 972-818-2924DetroitNovi, MI Tel: 248-848-4000Houston, TX Tel: 281-894-5983IndianapolisNoblesville, IN Tel: 317-773-8323Fax: 317-773-5453Los AngelesMission Viejo, CA Tel: 949-462-9523 Fax: 949-462-9608New York, NY Tel: 631-435-6000San Jose, CA Tel: 408-735-9110Canada - TorontoTel: 905-673-0699 Fax: 905-673-6509

ASIA/PACIFICAsia Pacific OfficeSuites 3707-14, 37th FloorTower 6, The GatewayHarbour City, KowloonHong KongTel: 852-2943-5100Fax: 852-2401-3431Australia - SydneyTel: 61-2-9868-6733Fax: 61-2-9868-6755China - BeijingTel: 86-10-8569-7000 Fax: 86-10-8528-2104China - ChengduTel: 86-28-8665-5511Fax: 86-28-8665-7889China - ChongqingTel: 86-23-8980-9588Fax: 86-23-8980-9500China - HangzhouTel: 86-571-8792-8115 Fax: 86-571-8792-8116China - Hong Kong SARTel: 852-2943-5100 Fax: 852-2401-3431China - NanjingTel: 86-25-8473-2460Fax: 86-25-8473-2470China - QingdaoTel: 86-532-8502-7355Fax: 86-532-8502-7205China - ShanghaiTel: 86-21-5407-5533 Fax: 86-21-5407-5066China - ShenyangTel: 86-24-2334-2829Fax: 86-24-2334-2393China - ShenzhenTel: 86-755-8864-2200 Fax: 86-755-8203-1760China - WuhanTel: 86-27-5980-5300Fax: 86-27-5980-5118China - XianTel: 86-29-8833-7252Fax: 86-29-8833-7256China - XiamenTel: 86-592-2388138 Fax: 86-592-2388130China - ZhuhaiTel: 86-756-3210040 Fax: 86-756-3210049

ASIA/PACIFICIndia - BangaloreTel: 91-80-3090-4444 Fax: 91-80-3090-4123India - New DelhiTel: 91-11-4160-8631Fax: 91-11-4160-8632India - PuneTel: 91-20-3019-1500Japan - OsakaTel: 81-6-6152-7160 Fax: 81-6-6152-9310Japan - TokyoTel: 81-3-6880- 3770 Fax: 81-3-6880-3771Korea - DaeguTel: 82-53-744-4301Fax: 82-53-744-4302Korea - SeoulTel: 82-2-554-7200Fax: 82-2-558-5932 or 82-2-558-5934Malaysia - Kuala LumpurTel: 60-3-6201-9857Fax: 60-3-6201-9859Malaysia - PenangTel: 60-4-227-8870Fax: 60-4-227-4068Philippines - ManilaTel: 63-2-634-9065Fax: 63-2-634-9069SingaporeTel: 65-6334-8870Fax: 65-6334-8850Taiwan - Hsin ChuTel: 886-3-5778-366Fax: 886-3-5770-955Taiwan - KaohsiungTel: 886-7-213-7830Taiwan - TaipeiTel: 886-2-2508-8600 Fax: 886-2-2508-0102Thailand - BangkokTel: 66-2-694-1351Fax: 66-2-694-1350

EUROPEAustria - WelsTel: 43-7242-2244-39Fax: 43-7242-2244-393Denmark - CopenhagenTel: 45-4450-2828 Fax: 45-4485-2829France - ParisTel: 33-1-69-53-63-20 Fax: 33-1-69-30-90-79Germany - DusseldorfTel: 49-2129-3766400Germany - MunichTel: 49-89-627-144-0 Fax: 49-89-627-144-44Germany - PforzheimTel: 49-7231-424750Italy - Milan Tel: 39-0331-742611 Fax: 39-0331-466781Italy - VeniceTel: 39-049-7625286 Netherlands - DrunenTel: 31-416-690399 Fax: 31-416-690340Poland - WarsawTel: 48-22-3325737 Spain - MadridTel: 34-91-708-08-90Fax: 34-91-708-08-91Sweden - StockholmTel: 46-8-5090-4654UK - WokinghamTel: 44-118-921-5800Fax: 44-118-921-5820

Worldwide Sales and Service

03/25/14

http://support.microchip.com

http://www.microchip.com