001/**
002 * Copyright (c) 2014 Digi International Inc.,
003 * All rights not expressly granted are reserved.
004 *
005 * This Source Code Form is subject to the terms of the Mozilla Public
006 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
007 * You can obtain one at http://mozilla.org/MPL/2.0/.
008 *
009 * Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343
010 * =======================================================================
011 */
012package com.digi.xbee.api.packet.common;
013
014import java.util.LinkedHashMap;
015
016import com.digi.xbee.api.models.ModemStatusEvent;
017import com.digi.xbee.api.packet.APIFrameType;
018import com.digi.xbee.api.packet.XBeeAPIPacket;
019import com.digi.xbee.api.utils.HexUtils;
020
021/**
022 * This class represents a Modem Status packet. Packet is built using the 
023 * parameters of the constructor or providing a valid API payload.
024 * 
025 * <p>RF module status messages are sent from the module in response to specific 
026 * conditions and indicates the state of the modem in that moment.</p>
027 * 
028 * @see com.digi.xbee.api.packet.XBeeAPIPacket
029 */
030public class ModemStatusPacket extends XBeeAPIPacket {
031
032        // Constants.
033        private static final int MIN_API_PAYLOAD_LENGTH = 2; // 1 (Frame type) + 1 (Modem status)
034        
035        // Variables.
036        private ModemStatusEvent modemStatusEvent;
037        
038        /**
039         * Creates a new {@code ModemStatusPacket} object from the given payload.
040         * 
041         * @param payload The API frame payload. It must start with the frame type 
042         *                corresponding to a Modem Status packet ({@code 0x8A}).
043         *                The byte array must be in {@code OperatingMode.API} mode.
044         * 
045         * @return Parsed Modem Status packet.
046         * 
047         * @throws IllegalArgumentException if {@code payload[0] != APIFrameType.MODEM_STATUS.getValue()} or
048         *                                  if {@code payload.length < {@value #MIN_API_PAYLOAD_LENGTH}}.
049         * @throws NullPointerException if {@code payload == null} or 
050         *                              if {@code modemStatusEvent == null}.
051         */
052        public static ModemStatusPacket createPacket(byte[] payload) {
053                if (payload == null)
054                        throw new NullPointerException("Modem Status packet payload cannot be null.");
055                
056                // 1 (Frame type) + 1 (Modem status)
057                if (payload.length < MIN_API_PAYLOAD_LENGTH)
058                        throw new IllegalArgumentException("Incomplete Modem Status packet.");
059                
060                if ((payload[0] & 0xFF) != APIFrameType.MODEM_STATUS.getValue())
061                        throw new IllegalArgumentException("Payload is not a Modem Status packet.");
062                
063                // Get the Modem status byte (byte 1).
064                int status = payload[1] & 0xFF;
065                
066                // Get the Modem Status enum. entry.
067                ModemStatusEvent modemStatusEvent = ModemStatusEvent.get(status);
068                
069                return new ModemStatusPacket(modemStatusEvent);
070        }
071        
072        /**
073         * Class constructor. Instantiates a new {@code ModemStatusPacket} object
074         * with the given modem status.
075         * 
076         * @param modemStatusEvent Modem status event enum. entry.
077         * 
078         * @throws NullPointerException if {@code modemStatusEvent == null}.
079         */
080        public ModemStatusPacket(ModemStatusEvent modemStatusEvent) {
081                super(APIFrameType.MODEM_STATUS);
082                
083                if (modemStatusEvent == null)
084                        throw new NullPointerException("Modem Status event cannot be null.");
085                
086                this.modemStatusEvent = modemStatusEvent;
087        }
088        
089        /*
090         * (non-Javadoc)
091         * @see com.digi.xbee.api.packet.XBeeAPIPacket#getAPIPacketSpecificData()
092         */
093        @Override
094        public byte[] getAPIPacketSpecificData() {
095                byte[] data = new byte[1];
096                data[0] = (byte)(modemStatusEvent.getId() & 0xFF);
097                return data;
098        }
099        
100        /*
101         * (non-Javadoc)
102         * @see com.digi.xbee.api.packet.XBeeAPIPacket#needsAPIFrameID()
103         */
104        @Override
105        public boolean needsAPIFrameID() {
106                return false;
107        }
108        
109        /**
110         * Returns modem status event enum. entry.
111         * 
112         * @return Modem status event enum. entry.
113         */
114        public ModemStatusEvent getStatus() {
115                return modemStatusEvent;
116        }
117        
118        /*
119         * (non-Javadoc)
120         * @see com.digi.xbee.api.packet.XBeeAPIPacket#isBroadcast()
121         */
122        @Override
123        public boolean isBroadcast() {
124                return false;
125        }
126        
127        /*
128         * (non-Javadoc)
129         * @see com.digi.xbee.packet.XBeeAPIPacket#getAPIPacketParameters()
130         */
131        @Override
132        public LinkedHashMap<String, String> getAPIPacketParameters() {
133                LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
134                parameters.put("Status", HexUtils.prettyHexString(HexUtils.integerToHexString(modemStatusEvent.getId(), 1)) + " (" + modemStatusEvent.getDescription() + ")");
135                return parameters;
136        }
137}