AN452 WIRELESS M-BUS STACK PROGRAMMER’S GUIDE

Rev. 0.1 2/10 Copyright © 2010 by Silicon Laboratories AN452 AN452 WIRELESS M-BUS STACK PROGRAMMER’S GUIDE 1. Overview This specification describes in detail the Application Programmer Interface (API) for the Silicon Labs Wireless M-Bus stack. The Silicon Labs Wireless M-Bus stack uses a Silicon Labs C8051 MCU and EZRadioPRO®. Wireless M-Bus is a European standard for meter reading applications using the 868 MHz frequency band. 1.1. Stack Layers Wireless M-Bus uses the 3-layer IEC model, which is a subset of the 7-layer OSI model. See Figure 1. Figure 1. Stack Layers The Physical Layer (PHY) is defined in EN 13757-4. The Physical Layer defines how the bits are encoded and transmitted, the RF modem characteristics (chip rate, preamble, and synchronization word), and RF parameters (modulation, center frequency, and frequency deviation). The PHY layer is implemented using a combination of hardware and firmware. The EZRadioPRO® performs all of the RF and modem functions. The EZRadioPRO is used in FIFO mode with the packet handler disabled. The MbusPhy.c module provides SPI interface, encoding/decoding, block read/write, and packet handling and manages the transceiver states. The M-Bus Data Link Layer is implemented in the MbusLink.c module. The M-Bus Application Programming interface consists of public functions that may be called from the Application Layer in the main thread. The MbusLink module also implements the Data Link Layer. The Data Link Layer will format and copy data from the application TX buffer to the MbusPhy TX buffer, adding the required headers and CRCs. The Application layer itself is not part of the M-Bus firmware. The Application Layer defines how a wide variety of data is to be formatted for transmission. Most meters only need to transmit one or two types of data. Adding a large amount of code to accommodate any kind of data to the meter would add unnecessary code and cost to the meter. If might be feasible to implement a library or a header file with an exhaustive list of data types. However, most metering customers know exactly what kind of data they need to transmit and can refer to the standard for formatting details. A universal reader or sniffer might implement a complete set of application data types on the PC GUI. For these reasons, the Application Layer is implemented using example applications for a meter and reader. PHY EN 13757-4 Data Link EN 60870-5-2 Application EN 13757-3 phy Si443x MCU M-Bus app AN452 2 Rev. 0.1 1.2. Required Standards 1.2.1. EN 13757-4 EN 13757-4 Communication system for meters and remote reading of meters Part 4: Wireless meter readout Radio meter reading for operation in the 868 MHz to 870 MHz SRD band 1.2.2. EN 13757-3 Communication system for meters and remote reading of meters Part 3: Dedicated Application Layer 1.2.3. IEC 60870-2-1:1992 Telecontrol equipment and systems Part 5: Transmission protocols Section 1:Link transmission procedure 1.2.4. IEC 60870-1-1:1990 Telecontrol equipment and systems Part 5: Transmission protocols Section 1: Transmission frame formats 1.3. Definitions  M-Bus—M-Bus is a wired standard for meter reading in Europe.  Wireless M-Bus—Wireless M-Bus for meter reading applications in Europe.  PHY—Physical Layer defines how data bits and bytes are encoded and transmitted.  API—Application Programmer interface.  LINK—Data Link Layer- defines how blocks and frames are transmitted.  CRC—Cyclic Redundancy Check.  FSK—Frequency Shift Keying.  Chip—Smallest unit of transmitted data. One data bit is encoded as multiple chips.  Module—A C code source .c file. 1.4. Coding Conventions The following conventions were adopted for this project:  The compiler_defs.h file is used for cross compiler support.  Memory specific pointers are used for buffers and module registers.  Each module has a short descriptive file name. MbusLink.c MbusPhy.c  Public functions include a short module prefix: MbusLink—mbus API MbusPhy—PHY module  Public variables also include the same module prefix, starting with a capital letter, since they are globals. MbusLink—mbus API MbusPhy—PHY module AN452 Rev. 0.1 3  Each module includes an API header file with public function prototypes. MbusLink.h MbusPhy.h  Module public bits and variables are declared external in the module header file.  Public variables are bit or byte only, or qualified using a binary semaphore.  Public variables are used sparingly.  No module includes external variables from another module  Public variable declarations and internal prototypes are located in the module source file.  Hardware-specific macros and bit definitions are located in a hardware_defs.h header file.  Compile time build options, memory specifiers macros, and buffer size macros are located in the module _defs.h files.  Function parameters passed as inputs may be indicated using __in, and parameters passed as outputs may be indicated using __out. AN452 4 Rev. 0.1 2. PHY API 2.1. PHY Layer Modules and File Organization 2.2. Functions 2.2.1. MbusPhyInitRegisters Prototype: PHY_STATUS MbusPhyInitRegisters(void); Parameters: none Returns: PHY_STATUS (U8) status: PHY_STATUS_SUCCESS PHY_STATUS_ERROR_INVALID_STATE Description: The PhyInitRegisters() function should be called after resetting the MCU, from the main() function, before using any other PHY functions. This function will initialize the internal PHY registers in the MCU memory to their default values. This function does not use the SPI or radio hardware. It must be called while the radio is in shutdown mode. If the PHY is not in the shutdown state, this function will return the error code PHY_STATUS_ERROR_INVALID_STATE. Table 1. PHY Layer Modules and File Organization File Name Description Comments MbusPhy.h Physical Layer header file MbusPhy.c Physical Layer c file MbusPhy_const.h Physical Layer constants header file MbusPhy_const.c Physical Layer constants c file Code constants used for Radio con- figuration hardware_defs.h Hardware definitions file hardware specific macros MbusPhy_def.h M-Bus definitions file M-Bus build and configuration options si443x_B1.h Si4432 header file compiler_defs.h Compiler definitions file cross compiler macros C8051F930_defs.h F930 header file AN452 Rev. 0.1 5 2.2.2. MbusPhyPowerUp Prototype: PHY_STATUS MbusPhyPowerUp (void); Parameters: none Returns: PHY_STATUS (U8) status: PHY_STATUS_SUCCESS PHY_STATUS_ERROR_INVALID_STATE Description: This function will power up the radio from the shutdown state. Note that the time to go into IDLE state depends on the current PHY state. Shutdown  Idle (17 ms) Standby  Idle (1 ms) While it is possible to call the MBusPhyIdle() function directly from shutdown, the MCU will be waiting a long time for the radio to complete the power on reset sequence. The MCU can perform tasks while the Radio is powering up by using the MbusPhyPowerUp() function first. The MBusPhyIdle() function should be called before using any PHY functions that require the PHY to be in the Idle or standby state. This can be used to perform tasks while waiting for Idle mode. MbusPhyPowerUp (); // This code is performed while the crystal is starting. MbusPhyRadioIdle (); 2.2.3. MbusPhyIdle Prototype: PHY_STATUS MbusPhyIdle (void); Parameters: none Returns: PHY_STATUS (U8) status: PHY_STATUS_SUCCESS PHY_STATUS_ERROR_POR_TIMEOUT PHY_STATUS_ERROR_XTAL_TIMEOUT PHY_STATUS_ERROR_INVALID_STATE Description: This function will put the PHY into IDLE state from any other state. Note that the time to go into IDLE state depends on the current radio state. Shutdown  Idle (17 ms) Standby  Idle (1 ms) RX  Idle (does not wait) The MbusPhyPowerUp function may be used to perform tasks while waiting for the radio to power up. MbusPhyPowerUp (); // This code is performed while the crystal is starting. MbusPhyRadioIdle (); AN452 6 Rev. 0.1 The next higher layer does not need to know the current state of the Radio, but the execution time of this function will vary greatly depending on the current radio mode. 2.2.4. MbusPhyStandby Prototype: PHY_STATUS MbusPhyStandby (void); Parameters: Returns: PHY_STATUS (U8) status: PHY_STATUS_SUCCESS PHY_STATUS_ERROR_POR_TIMEOUT Description: This function will put the PHY (Radio) into Standby mode from any other mode. Note that the time to go into Standby mode depends on the current radio mode. Shutdown  Standby (16 ms) RX  Standby – 0 (does not wait) Idle  Standby – 0 (does not wait) Normally, this function should not be used from ShutDown mode. The radio automatically goes from ShutDown to Idle mode following a POR. If this function is called when the Radio is in Shutdown mode, the MCU will wait until the POR is complete. 2.2.5. MbusPhyInit Prototype: PHY_STATUS MbusPhyInit(void); Parameters: none Returns: PHY_STATUS (U8) status: PHY_STATUS_SUCCESS PHY_STATUS_ERROR_INVALID_STATE PHY_STATUS_ERROR_UNSUPPORTED_RADIO Description: The MBusPhyInit() function will initialize the Si443x internal registers. The PHY must be in the IDLE state before calling MBusPhyInit(). This may be accomplished by calling MbusPhyIdle () before MBusPhyInit(). The PHY_METER and PHY_MODE registers should be set using the MbusPhySet() command before calling the MbusPhyInit() function. Otherwise the default values will be used. Since the Si4431 register values are lost, the PHY must be initialized every time after it is powered down. When using the asymmetric T2 transfer mode, this function will not initialize the radio registers since the radio registers are initialized upon each MbusPhyTx() or MbusPhyRx() function. The status return code need not be used. In most cases, the next higher layer should know not to call this function from an invalid state. AN452 Rev. 0.1 7 2.2.6. MbusPhyRadioShutDown Prototype: PHY_STATUS MbusPhyRadioShutDown (void); Parameters: none Returns: PHY_STATUS (U8) status PHY_STATUS_SUCCESS This function will put the Radio into shutdown mode from any other mode. The radio crystal is turned off manually before shutting down the chip. This function does not use any timeouts. All radio register values will be lost in shutdown mode. 2.2.7. MbusPhyGet Prototype: PHY_STATUS MbusPhyGet(U8 addr, U8 *value); Parameters: U8 addr – The PHY variable address (enumeration) U8 *value – generic byte pointer to data Returns: PHY_STATUS (U8) status: PHY_STATUS _SUCCESS PHY_STATUS_ERROR_INVALID_ADDRESS Description: The MbusPhyGet function can be used to read the PHY registers or Si4431 registers. 0x00-0x7F—Si443x registers (SPI read transfer) 0x80-0x84—MbusPhy module registers 0x85-0xFF—returns invalid address The SPI transfers are blocking, and this function will block until two bytes are transferred. This will take at least 1.6 µs using a 10 MHz SPI clock. The status return code will return an error if the address is invalid. The status return code need not be used. In most cases, the next higher layer should know not to pass an invalid address. 2.2.8. MbusPhySet Prototype: U8 MbusPhySet(U8 addr, U8 value); Parameters: U8 addr—The PHY variable address (enumeration) U8 value Returns: PHY_STATUS (U8) status: PHY_STATUS_SUCCESS PHY_STATUS_ERROR_INVALID_VALUE PHY_STATUS_ERROR_READ_ONLY_ADDRESS PHY_STATUS_ERROR_INVALID_ADDRESS AN452 8 Rev. 0.1 Description: The MbusPhySet function can be used to set the PHY module registers or Si4431 registers. 0x00-0x7F – Si443x registers (SPI write transfer) 0x80-0x84 – MbusPhy module registers 0x85-0xFF – returns invalid address The status return code will return an error if the value is out of range or read only. The status return code need not be used. In most cases, the next higher layer should know not to write an invalid value, read only address, or invalid address. The SPI transfers are blocking, and this function will block until two bytes are transferred. This will take at least 1.6 µs using a 10 MHz SPI clock. 2.2.9. MbusPhyTx Prototype: PHY_STATUS MbusPhyTX(VARIABLE_SEGMENT_POINTER(, U8, BUFFER_MSPACE)); Parameters: VARIABLE_SEGMENT_POINTER(buffer, U8, BUFFER_MSPACE)); pointer to TX buffer in BUFFER_MSPACE (typically xdata) Returns: PHY_STATUS (U8) status: PHY_STATUS_SUCCESS PHY_STATUS_ERROR_INVALID_STATE—not in IDLE state PHY_STATUS_ERROR_INVALID_LENGTH—invalid L field PHY_STATUS_ERROR_TX_TIMEOUT—Radio failed to send message before timeout Description: This function will transmit the data in the transmit buffer. This function is blocking and will not return until transmission is complete. If the asymmetric Mode T2 is being used, the radio will be initialized for TX. The L field is read from the first byte of the buffer and need not be passed as a parameter. The packet length, number of blocks, and the number of encoded bytes is calculated from the L field. The number of encoded bytes is written to the radio TX packet length. The packet in the TX buffer should be properly formatted (by the Data Link Layer) into blocks with CRCs between blocks. The next higher layer should supply a buffer large enough to accommodate the entire packet as indicated by the L field. The TX function may send garbage data in the case of a buffer overrun. The TX function does not write to the TX buffer. This function will copy the first 64 bytes into the radio FIFO. Each byte of data is encoded before writing to the SPI. If additional bytes are to be sent, the FIFO almost empty threshold will be set to 16 bytes and the FIFO almost empty interrupt will be enabled. If there are not additional bytes to be written, the FIFO almost empty will be cleared to 0, and the Packet Sent interrupt will be enabled. Once the FIFO has been initialized and interrupts have been enabled, the transmitter will be started by writing to the Function control 1 register. The MCU will then go to sleep until the next IRQ wakeup or timeout. If the PHY is not in the IDLE state, the function will immediately return a PHY_STATUS_ERROR_INVALID_STATE error code. If the first byte in the buffer is an invalid length for the L field, the function will immediately return a PHY_STATUS_ERROR_INVALID_LENGTH error code. If for any reason the Radio does not successfully transmit all of the data in the TX buffer, the radio will be manually set into the IDLE mode, and this function will return the PHY_STATUS_ERROR_TX_TIMEOUT error code. This generally indicates a problem with the hardware. AN452 Rev. 0.1 9 2.2.10. MbusPhyRx Prototype: PHY_STATUS MbusPhyRX(U32, VARIABLE_SEGMENT_POINTER(, U8, BUFFER_MSPACE)); Parameters: U32 timeout—ticks of 32.768 kHz clock. VARIABLE_SEGMENT_POINTER(buffer, U8, BUFFER_MSPACE)); pointer to RX buffer in BUFFER_MSPACE (typically xdata) Returns: U8 status PHY_STATUS_SUCCESS PHY_STATUS_ERROR_NOTHING_RECEIVED—nothing receive in RX time PHY_STATUS_ERROR_INVALID_STATE—not in IDLE state PHY_STATUS_ERROR_INVALID_LENGTH—invalid received L field PHY_STATUS_ERROR_DECODING—error decoding Manchester or 3 out of 6 PHY_STATUS_ERROR_RX_INCOMPLETE—incomplete message received Description: The MbusPhyRx() function is a blocking RX function with a timeouts. The receiver will remain on for the specified amount of time with the MCU in low-power sleep mode. The timeout or receiver interrupt will wake up the MCU. The next higher layer should supply a buffer large enough to accommodate the entire packet for the largest possible L-field of interest. The largest L-field of interest should be defined in Mbus_defs.h #define USER_RX_MAX_L_FIELD 148 An example buffer declaration is shown below: SEGMENT_VARIABLE( userBuffer[USER_RX_BUFFER_SIZE], U8, BUFFER_MSPACE) The return status of this function will indicate if a packet has been successfully received. If a packet has been successfully received, this function will return a status of PHY_STATUS_SUCCESS. The PHY does not validate the CRCs; so, the packet still might contain a CRC error. If the receiver timeout has expired, the function will return a status of PHY_STATUS_ERROR_NOTHING_RECEIVED. This may not be an error in many circumstances. A decoding error at any point after the SYNC word results in the Receiver immediately returning a status of PHY_STATUS_ERROR_DECODING. If the correct number of bytes is not received completely, a status of PHY_STATUS_ERROR_RX_INCOMPLETE will be returned. 2.3. PHY Module Registers This it the structure typedef for the Mbus PHY typedef struct MbusPhyRegisters { U8 meter; U8 mode; U8 channel; U8 state; U8 RxPacketLength; U8 RxRSSI; } MbusPhyRegisters; All PHY module registers can be read using the MbusPhySet() function. AN452 10 Rev. 0.1 3. Data Link Layer API The Data Link Layer module implements a 13757-4:2005 compliant link layer. The Data Link Layer (LINK) provides an interface between the Physical Layer (PHY) and the Application Layer (AL). Data Link Layer:  Provides functions that transfer data between PHY and AL  Generate CRCs for outgoing messages  Detect CRC errors in incoming messages  Provide physical addressing  Acknowledge transfers for bidirectional communication modes  Frame data bits  Detect framing errors in incoming messages 3.1. Definitions  AL—Application Layer  LINK—Data Link Layer  NHL—Next Higher Layer  PHY—Physical Layer 3.2. Module and File Organization Table 2. File Descriptions and Comments File Name Description Comments Common.h Common typedefs and macros Crc.h CRC-16-DNP header file Crc.c CRC-16-DNP source file MbusLink.h Data Link Layer header file MbusLink.c Data Link Layer source file MbusLinkServices.h Data Link Layer Services primitives header file MbusLinkServices.c Data Link Layer Services primitives source file Optional request, confirmation, indi- cation, and response service primi- tives. MbusLink_defs.h Data Link Layer compile-time build options MbusLinkServices_defs.h Data Link Layer Services compile-time build options AN452 Rev. 0.1 11 3.3. Functions 3.3.1. MbusLinkInit Prototype: LINK_STATUS MbusLinkInit(void); Parameters: none Returns: LINK_STATUS_SUCCESS LINK_STATUS_PHY_ERROR_INVALID_STATE Description: This function initializes the Data Link Layer module attributes to their default values, initializes the RTC at 32.768 kHz, and initializes the PHY registers. This function only needs to be called once at the beginning of code after an MCU reset. 3.3.2. MbusLinkRadioPowerOn Prototype: LINK_STATUS MbusLinkRadioPowerOn(void); Parameters: none Returns: LINK_STATUS_SUCCESS LINK_STATUS_PHY_ERROR_INVALID_STATE Description: This function turns on the EZRadioPRO® but does not wait for the radio to enter IDLE mode. The NHL/AL can perform work while waiting for the radio oscillator to stabilize. Next, call MbusLinkRadioConfig() to wait for the radio to enter IDLE mode and configure the radio modes and channel. 3.3.3. MbusLinkRadioConfig Prototype: LINK_STATUS MbusLinkRadioConfig(void); Parameters: none Returns: LINK_STATUS_SUCCESS LINK_STATUS_PHY_ERROR_INVALID_VALUE LINK_STATUS_PHY_ERROR_INVALID_STATE LINK_STATUS_PHY_ERROR_POR_TIMEOUT LINK_STATUS_PHY_ERROR_XTAL_TIMEOUT LINK_STATUS_PHY_ERROR_UNSUPPORTED_RADIO Description: This function waits for the EZRadioPRO to enter IDLE mode and stores the radio modes and channel settings before configuring the radio over SPI. Users must call this function after changing radio settings before the new settings will apply. AN452 12 Rev. 0.1 3.3.4. MbusLinkRadioPowerOff Prototype: LINK_STATUS MbusLinkRadioPowerOff(void); Parameters: none Returns: LINK_STATUS_SUCCESS LINK_STATUS_PHY_ERROR_INVALID_STATE Description: Turns the EZRadioPRO off. All radio settings are lost when the radio is shut down. Call MbusLinkRadioPowerOn() and MbusLinkRadioConfig() before using the radio again. 3.3.5. MbusLinkRadioStandby Prototype: LINK_STATUS MbusLinkRadioStandby(void); Parameters: none Returns: LINK_STATUS_SUCCESS LINK_STATUS_PHY_ERROR_POR_TIMEOUT LINK_STATUS_PHY_ERROR_INVALID_STATE Description: Puts the EZRadioPRO into a low power standby mode. Radio