    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.packet.XBeeAPIPacket#getAPIPacketParameters()
    121         */
    122        @Override
    123        public LinkedHashMap<String, String> getAPIPacketParameters() {
    124                LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
    125                parameters.put("Status", HexUtils.prettyHexString(HexUtils.integerToHexString(modemStatusEvent.getId(), 1)) + " (" + modemStatusEvent.getDescription() + ")");
    126                return parameters;
    127        }
    128}