Update surv.py

pyModeS/decoder/surv.py

@@ -1,120 +1,132 @@
 """
-Warpper for short roll call surveillance replies DF=4/5
+Decode short roll call surveillance replies, with downlink format 4 or 5
-
 """
 
 from pyModeS import common
 
+
+def _checkdf(func):
+    """Ensure downlink format is 4 or 5."""
+
+    def wrapper(msg):
+        df = common.df(msg)
+        if df not in [4, 5]:
+            raise RuntimeError(
+                "Incorrect downlink format, expect 4 or 5, got {}".format(df)
+            )
+        return func(msg)
+
+    return wrapper
+
+
+@_checkdf
 def fs(msg):
-    '''tell the flight status of the aircraft, returns airborne, ground or None'''
+    """Decode flight status.
-    if common.df(msg) in [4,5]:
-        binaryraw=common.hex2bin(msg)
-        fs=int(binaryraw[5:8],2)
-        if fs in [0,2]:
-            return "airborne"
-        if fs in [1,3]:
-            return "ground"
-        else:
-            return None
-    else:
-        raise RuntimeError("Incorrect or inconsistent message types")
 
-def alert(msg):
+    Args:
-    '''returns True if there is an alert, False otherwise '''
+        msg (str): 14 hexdigits string
-    #The alert indicates that the TXPPR Mode A code is changed manually by the pilot. Icao Annex10, Vol IV, 3.1.2.6.10.1.1
+    Returns:
-    if common.df(msg) in [4,5]:
+        int, str: flight status, description
-        binaryraw = common.hex2bin(msg)
+
-        fs = int(binaryraw[5:8], 2)
+    """
-        if fs in [2,3,4]:
+    msgbin = common.hex2bin(msg)
-            return True
+    fs = common.bin2int(msgbin[5:8])
-        if fs in [0,1,5]:
+    text = None
-            return False
+
-        else:
+    if fs == 0:
-            return None
+        text = "no alert, no SPI, aircraft is airborne"
-    else:
+    elif fs == 1:
-        raise RuntimeError("Incorrect or inconsistent message types")
+        text = "no alert, no SPI, aircraft is on-ground"
+    elif fs == 2:
+        text = "alert, no SPI, aircraft is airborne"
+    elif fs == 3:
+        text = "alert, no SPI, aircraft is on-ground"
+    elif fs == 4:
+        text = "alert, SPI, aircraft is airborne or on-ground"
+    elif fs == 5:
+        text = "no alert, SPI, aircraft is airborne or on-ground"
+
+    return fs, text
 
 
-def SPI(msg):
+@_checkdf
-    '''returns True if there there is Special Pulse Indicator, False otherwise '''
-    if common.df(msg) in [4, 5]:
-        binaryraw = common.hex2bin(msg)
-        fs = int(binaryraw[5:8], 2)
-        if fs in [4, 5]:
-            return True
-        if fs in [0, 1, 2, 3]:
-            return False
-        else:
-            return None
-    else:
-        raise RuntimeError("Incorrect or inconsistent message types")
-
 def dr(msg):
-    '''Returns Downlink Request Status.
+    """Decode downlink request.
+
     Args:
-        msg (str): 14 hexdigits string,
+        msg (str): 14 hexdigits string
     Returns:
-        str: Downlink Request Status
+        int, str: downlink request, description
-    '''
+
-    if common.df(msg) in [4,5]:
+    """
-        binaryraw = common.hex2bin(msg)
+    msgbin = common.hex2bin(msg)
-        dr = int(binaryraw[8:13], 2)
+    dr = common.bin2int(msgbin[8:13])
-        if dr in [2,3,6,7]:
+
-            return "ACAS"
+    text = None
+
     if dr == 0:
-            return "no downlink request"
+        text = "no downlink request"
-        if dr == 1:
+    elif dr == 1:
-            return "request to send Comm-B message"
+        text = "request to send Comm-B message"
-        if dr in 4:
+    elif dr == 4:
-            return "Comm-B broadcast 1 available"
+        text = "Comm-B broadcast 1 available"
-        if dr in 5:
+    elif dr == 5:
-            return "Comm-B broadcast 2 available"
+        text = "Comm-B broadcast 2 available"
-        if dr > 7 and dr < 16:
+    elif dr >= 16:
-            return None
+        text = "ELM downlink segments available: {}".format(dr - 15)
-        else:
-            return str(15-dr)+" downlink ELM segments available"
-    else:
-        raise RuntimeError("Incorrect or inconsistent message types")
 
+    return dr, text
+
+
+@_checkdf
 def um(msg):
-    '''returns the Interrogator Identifier and the type of reservation
+    """Decode utility message.
+
+    Utility message contains interrogator identifier and reservation type.
+
     Args:
-        msg (str): 14 hexdigits string,
+        msg (str): 14 hexdigits string
     Returns:
-        int: II code of the identifier that triggered the reply
+        int, str: interrogator identifier code that triggered the reply, and
-        str: type of reservation made by the interrogator
+        reservation type made by the interrogator
-    '''
+    """
-    if common.df(msg) in [4,5]:
+    msgbin = common.hex2bin(msg)
-        binaryraw = common.hex2bin(msg)
+    iis = common.bin2int(msgbin[13:17])
-        iis = int(binaryraw[13:17], 2)
+    ids = common.bin2int(msgbin[17:19])
-        ds = int(binaryraw[17:19], 2)
+    if ids == 0:
-        if ds == 0:
+        ids_text = None
-            ds=None
+    if ids == 1:
-        if ds == 1:
+        ids_text = "Comm-B interrogator identifier code"
-            ds='Comm-B'
+    if ids == 2:
-        if ds == 2:
+        ids_text = "Comm-C interrogator identifier code"
-            ds='Comm-C'
+    if ids == 3:
-        if ds == 3:
+        ids_text = "Comm-D interrogator identifier code"
-            ds='Comm-D'
+    return iis, ids, ids_text
-        return iis, ds
 
-    else:
-        raise RuntimeError("Incorrect or inconsistent message types")
 
-def ac(msg):
+@_checkdf
-    '''return the altitude in ft'''
+def altitude(msg):
-    if common.df(msg) == 4:
+    """Decode altitude.
-        binaryraw = common.hex2bin(msg)
-        altcode = binaryraw[19:32] # Here we could also put the common.altcode(msg).
-        return common.altitude(altcode)
-    else:
-        raise RuntimeError("Incorrect or inconsistent message types")
 
-def id(msg):
+    Args:
-    '''return the squawk code (identifier)'''
+        msg (String): 14 hexdigits string
-    if common.df(msg) == 5:
+
-        binaryraw = common.hex2bin(msg)
+    Returns:
-        altcode = binaryraw[19:32]  # Here we could also put the common.idcode(msg).
+        int: altitude in ft
-        return common.squawk(altcode)
+
-    else:
+    """
-        raise RuntimeError("Incorrect or inconsistent message types")
+    return common.altcode(msg)
+
+
+@_checkdf
+def identity(msg):
+    """Decode squawk code.
+
+    Args:
+        msg (String): 14 hexdigits string
+
+    Returns:
+        string: squawk code
+
+    """
+    return common.idcode(msg)