    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.raw;
    013
    014import java.util.LinkedHashMap;
    015
    016import com.digi.xbee.api.models.XBeeTransmitStatus;
    017import com.digi.xbee.api.packet.XBeeAPIPacket;
    018import com.digi.xbee.api.packet.APIFrameType;
    019import com.digi.xbee.api.utils.HexUtils;
    020
    021/**
    022 * This class represents a TX (Transmit) Status packet. Packet is built using
    023 * the parameters of the constructor or providing a valid API payload.
    024 *
    025 * <p>When a TX Request is completed, the module sends a TX Status message.
    026 * This message will indicate if the packet was transmitted successfully or if
    027 * there was a failure.</p>
    028 *
    029 * @see TX16Packet
    030 * @see TX64Packet
    031 * @see com.digi.xbee.api.packet.XBeeAPIPacket
    032 */
    033public class TXStatusPacket extends XBeeAPIPacket {
    034
    035        // Constants.
    036        private static final int MIN_API_PAYLOAD_LENGTH = 3; // 1 (Frame type) + 1 (frame ID) + 1 (status)
    037
    038        // Variables.
    039        private final XBeeTransmitStatus transmitStatus;
    040
    041        /**
    042         * Creates a new {@code TXStatusPacket} object from the given payload.
    043         *
    044         * @param payload The API frame payload. It must start with the frame type
    045         *                corresponding to a TX Status packet ({@code 0x89}).
    046         *                The byte array must be in {@code OperatingMode.API} mode.
    047         *
    048         * @return Parsed TX status packet.
    049         *
    050         * @throws IllegalArgumentException if {@code payload[0] != APIFrameType.TX_STATUS.getValue()} or
    051         *                                  if {@code payload.length < }{@value #MIN_API_PAYLOAD_LENGTH} or
    052         *                                  if {@code frameID < 0} or
    053         *                                  if {@code frameID > 255}.
    054         * @throws NullPointerException if {@code payload == null}.
    055         */
    056        public static TXStatusPacket createPacket(byte[] payload) {
    057                if (payload == null)
    058                        throw new NullPointerException("TX Status packet payload cannot be null.");
    059
    060                // 1 (Frame type) + 1 (frame ID) + 1 (status)
    061                if (payload.length < MIN_API_PAYLOAD_LENGTH)
    062                        throw new IllegalArgumentException("Incomplete TX Status packet.");
    063
    064                if ((payload[0] & 0xFF) != APIFrameType.TX_STATUS.getValue())
    065                        throw new IllegalArgumentException("Payload is not a TX Status packet.");
    066
    067                // payload[0] is the frame type.
    068                int index = 1;
    069
    070                // Frame ID byte.
    071                int frameID = payload[index] & 0xFF;
    072                index = index + 1;
    073
    074                // Status byte.
    075                int status = payload[index] & 0xFF;
    076
    077                // TODO if status is unknown????
    078                return new TXStatusPacket(frameID, XBeeTransmitStatus.get(status));
    079        }
    080
    081        /**
    082         * Class constructor. Instantiates a new {@code TXStatusPacket} object
    083         * with the given parameters.
    084         *
    085         * @param frameID Packet frame ID.
    086         * @param transmitStatus Transmit status.
    087         *
    088         * @throws IllegalArgumentException if {@code frameID < 0} or
    089         *                                  if {@code frameID > 255}.
    090         * @throws NullPointerException if {@code transmitStatus == null}.
    091         *
    092         * @see com.digi.xbee.api.models.XBeeTransmitStatus
    093         */
    094        public TXStatusPacket(int frameID, XBeeTransmitStatus transmitStatus) {
    095                super(APIFrameType.TX_STATUS);
    096
    097                if (transmitStatus == null)
    098                        throw new NullPointerException("Transmit status cannot be null.");
    099                if (frameID < 0 || frameID > 255)
    100                        throw new IllegalArgumentException("Frame ID must be between 0 and 255.");
    101
    102                this.frameID = frameID;
    103                this.transmitStatus = transmitStatus;
    104        }
    105
    106        /*
    107         * (non-Javadoc)
    108         * @see com.digi.xbee.api.packet.XBeeAPIPacket#getAPIPacketSpecificData()
    109         */
    110        @Override
    111        protected byte[] getAPIPacketSpecificData() {
    112                return new byte[] {(byte)transmitStatus.getId()};
    113        }
    114
    115        /*
    116         * (non-Javadoc)
    117         * @see com.digi.xbee.api.packet.XBeeAPIPacket#needsAPIFrameID()
    118         */
    119        @Override
    120        public boolean needsAPIFrameID() {
    121                return true;
    122        }
    123
    124        /**
    125         * Returns the transmit status.
    126         *
    127         * @return Transmit status.
    128         *
    129         * @see com.digi.xbee.api.models.XBeeTransmitStatus
    130         */
    131        public XBeeTransmitStatus getTransmitStatus() {
    132                return transmitStatus;
    133        }
    134
    135        /*
    136         * (non-Javadoc)
    137         * @see com.digi.xbee.api.packet.XBeeAPIPacket#getAPIPacketParameters()
    138         */
    139        @Override
    140        public LinkedHashMap<String, String> getAPIPacketParameters() {
    141                LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
    142                parameters.put("Status", HexUtils.prettyHexString(HexUtils.integerToHexString(transmitStatus.getId(), 1)) + " (" + transmitStatus.getDescription() + ")");
    143                return parameters;
    144        }
    145}