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#isBroadcast()
138         */
139        @Override
140        public boolean isBroadcast() {
141                return false;
142        }
143        
144        /*
145         * (non-Javadoc)
146         * @see com.digi.xbee.api.packet.XBeeAPIPacket#getAPIPacketParameters()
147         */
148        @Override
149        public LinkedHashMap<String, String> getAPIPacketParameters() {
150                LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
151                parameters.put("Status", HexUtils.prettyHexString(HexUtils.integerToHexString(transmitStatus.getId(), 1)) + " (" + transmitStatus.getDescription() + ")");
152                return parameters;
153        }
154}