<p>fixeria <strong>submitted</strong> this change.</p><p><a href="https://gerrit.osmocom.org/c/osmocom-bb/+/23132">View Change</a></p><div style="white-space:pre-wrap">Approvals:
laforge: Looks good to me, approved
pespin: Looks good to me, but someone else must approve
Jenkins Builder: Verified
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">trx_toolkit/data_msg.py: convert comments into docstrings<br><br>Change-Id: I856b54fd1baca4ae0edd2aa59be6a76372cef667<br>Related: OS#4006, SYS#4895<br>---<br>M src/target/trx_toolkit/data_msg.py<br>1 file changed, 75 insertions(+), 47 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/src/target/trx_toolkit/data_msg.py b/src/target/trx_toolkit/data_msg.py</span><br><span>index 86670fc..89fb916 100644</span><br><span>--- a/src/target/trx_toolkit/data_msg.py</span><br><span>+++ b/src/target/trx_toolkit/data_msg.py</span><br><span>@@ -122,54 +122,53 @@</span><br><span> CHDR_VERSION_MAX = 0b1111</span><br><span> known_versions = [0x00, 0x01]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Common constructor</span><br><span> def __init__(self, fn = None, tn = None, burst = None, ver = 0):</span><br><span> self.burst = burst</span><br><span> self.ver = ver</span><br><span> self.fn = fn</span><br><span> self.tn = tn</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # The common header length</span><br><span> @property</span><br><span> def CHDR_LEN(self):</span><br><span style="color: hsl(0, 100%, 40%);">- # (VER + TN) + FN</span><br><span style="color: hsl(0, 100%, 40%);">- return 1 + 4</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' The common header length. '''</span><br><span style="color: hsl(120, 100%, 40%);">+ return 1 + 4 # (VER + TN) + FN</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates message specific header</span><br><span> def gen_hdr(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate message specific header. '''</span><br><span> raise NotImplementedError</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Parses message specific header</span><br><span> def parse_hdr(self, hdr):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Parse message specific header. '''</span><br><span> raise NotImplementedError</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates message specific burst</span><br><span> def gen_burst(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate message specific burst. '''</span><br><span> raise NotImplementedError</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Parses message specific burst</span><br><span> def parse_burst(self, burst):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Parse message specific burst. '''</span><br><span> raise NotImplementedError</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generate a random message specific burst</span><br><span> def rand_burst(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate a random message specific burst. '''</span><br><span> raise NotImplementedError</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates a random frame number</span><br><span> def rand_fn(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate a random frame number. '''</span><br><span> return random.randint(0, GSM_HYPERFRAME)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates a random timeslot number</span><br><span> def rand_tn(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate a random timeslot number. '''</span><br><span> return random.randint(0, 7)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Randomizes the message header</span><br><span> def rand_hdr(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Randomize the message header. '''</span><br><span> self.fn = self.rand_fn()</span><br><span> self.tn = self.rand_tn()</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates human-readable header description</span><br><span> def desc_hdr(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate human-readable header description. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> result = ""</span><br><span> </span><br><span> if self.ver > 0:</span><br><span>@@ -186,28 +185,29 @@</span><br><span> </span><br><span> return result</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Converts unsigned soft-bits {254..0} to soft-bits {-127..127}</span><br><span> @staticmethod</span><br><span> def usbit2sbit(bits):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Convert unsigned soft-bits {254..0} to soft-bits {-127..127}. '''</span><br><span> return [-127 if (b == 0xff) else 127 - b for b in bits]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Converts soft-bits {-127..127} to unsigned soft-bits {254..0}</span><br><span> @staticmethod</span><br><span> def sbit2usbit(bits):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Convert soft-bits {-127..127} to unsigned soft-bits {254..0}. '''</span><br><span> return [127 - b for b in bits]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Converts soft-bits {-127..127} to bits {1..0}</span><br><span> @staticmethod</span><br><span> def sbit2ubit(bits):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Convert soft-bits {-127..127} to bits {1..0}. '''</span><br><span> return [int(b < 0) for b in bits]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Converts bits {1..0} to soft-bits {-127..127}</span><br><span> @staticmethod</span><br><span> def ubit2sbit(bits):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Convert bits {1..0} to soft-bits {-127..127}. '''</span><br><span> return [-127 if b else 127 for b in bits]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Validates the message fields (throws ValueError)</span><br><span> def validate(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Validate the message fields (throws ValueError). '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> if not self.ver in self.known_versions:</span><br><span> raise ValueError("Unknown TRXD header version %d" % self.ver)</span><br><span> </span><br><span>@@ -223,8 +223,9 @@</span><br><span> if self.tn < 0 or self.tn > 7:</span><br><span> raise ValueError("TDMA time-slot %d is out of range" % self.tn)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates a TRX DATA message</span><br><span> def gen_msg(self, legacy = False):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate a TRX DATA message. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Validate all the fields</span><br><span> self.validate()</span><br><span> </span><br><span>@@ -252,8 +253,9 @@</span><br><span> </span><br><span> return buf</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Parses a TRX DATA message</span><br><span> def parse_msg(self, msg):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Parse a TRX DATA message. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Make sure we have at least common header</span><br><span> if len(msg) < self.CHDR_LEN:</span><br><span> raise ValueError("Message is to short: missing common header")</span><br><span>@@ -311,9 +313,10 @@</span><br><span> # Specific message fields</span><br><span> pwr = None</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Calculates header length depending on its version</span><br><span> @property</span><br><span> def HDR_LEN(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Calculate header length depending on its version. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Common header length</span><br><span> length = self.CHDR_LEN</span><br><span> </span><br><span>@@ -325,8 +328,9 @@</span><br><span> </span><br><span> return length</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Validates the message fields (throws ValueError)</span><br><span> def validate(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Validate the message fields (throws ValueError). '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Validate common fields</span><br><span> DATAMSG.validate(self)</span><br><span> </span><br><span>@@ -344,8 +348,9 @@</span><br><span> if len(self.burst) not in (GSM_BURST_LEN, EDGE_BURST_LEN):</span><br><span> raise ValueError("Tx burst has odd length %u" % len(self.burst))</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates a random power level</span><br><span> def rand_pwr(self, min = None, max = None):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate a random power level. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> if min is None:</span><br><span> min = self.PWR_MIN</span><br><span> </span><br><span>@@ -354,13 +359,15 @@</span><br><span> </span><br><span> return random.randint(min, max)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Randomizes message specific header</span><br><span> def rand_hdr(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Randomize message specific header. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> DATAMSG.rand_hdr(self)</span><br><span> self.pwr = self.rand_pwr()</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates human-readable header description</span><br><span> def desc_hdr(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate human-readable header description. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Describe the common part</span><br><span> result = DATAMSG.desc_hdr(self)</span><br><span> </span><br><span>@@ -370,8 +377,9 @@</span><br><span> # Strip useless whitespace and return</span><br><span> return result.strip()</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates message specific header part</span><br><span> def gen_hdr(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate message specific header part. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Allocate an empty byte-array</span><br><span> buf = bytearray()</span><br><span> </span><br><span>@@ -380,18 +388,21 @@</span><br><span> </span><br><span> return buf</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Parses message specific header part</span><br><span> def parse_hdr(self, hdr):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Parse message specific header part. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Parse power level</span><br><span> self.pwr = hdr[5]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates message specific burst</span><br><span> def gen_burst(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate message specific burst. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Copy burst 'as is'</span><br><span> return bytearray(self.burst)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Parses message specific burst</span><br><span> def parse_burst(self, burst):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Parse message specific burst. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> length = len(burst)</span><br><span> </span><br><span> # Distinguish between GSM and EDGE</span><br><span>@@ -400,12 +411,13 @@</span><br><span> else:</span><br><span> self.burst = list(burst[:GSM_BURST_LEN])</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generate a random message specific burst</span><br><span> def rand_burst(self, length = GSM_BURST_LEN):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate a random message specific burst. '''</span><br><span> self.burst = [random.randint(0, 1) for _ in range(length)]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Transforms this message to TRX2L1 message</span><br><span> def gen_trx2l1(self, ver = None):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Transform this message to TRX2L1 message. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Allocate a new message</span><br><span> msg = DATAMSG_TRX2L1(fn = self.fn, tn = self.tn,</span><br><span> ver = self.ver if ver is None else ver)</span><br><span>@@ -539,9 +551,10 @@</span><br><span> tsc = None</span><br><span> ci = None</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Calculates header length depending on its version</span><br><span> @property</span><br><span> def HDR_LEN(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Calculate header length depending on its version. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Common header length</span><br><span> length = self.CHDR_LEN</span><br><span> </span><br><span>@@ -580,15 +593,17 @@</span><br><span> if len(self.burst) != self.mod_type.bl:</span><br><span> raise ValueError("Rx burst has odd length %u" % len(self.burst))</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Validates the burst (throws ValueError)</span><br><span> def validate_burst(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Validate the burst (throws ValueError). '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> if self.ver == 0x00:</span><br><span> self._validate_burst_v0()</span><br><span> elif self.ver >= 0x01:</span><br><span> self._validate_burst_v1()</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Validates the message header fields (throws ValueError)</span><br><span> def validate(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Validate the message header fields (throws ValueError). '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Validate common fields</span><br><span> DATAMSG.validate(self)</span><br><span> </span><br><span>@@ -635,8 +650,9 @@</span><br><span> </span><br><span> self.validate_burst()</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates a random RSSI value</span><br><span> def rand_rssi(self, min = None, max = None):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate a random RSSI value. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> if min is None:</span><br><span> min = self.RSSI_MIN</span><br><span> </span><br><span>@@ -645,8 +661,9 @@</span><br><span> </span><br><span> return random.randint(min, max)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates a ToA (Time of Arrival) value</span><br><span> def rand_toa256(self, min = None, max = None):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate a random ToA (Time of Arrival) value. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> if min is None:</span><br><span> min = self.TOA256_MIN</span><br><span> </span><br><span>@@ -655,8 +672,9 @@</span><br><span> </span><br><span> return random.randint(min, max)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Randomizes message specific header</span><br><span> def rand_hdr(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Randomize message specific header. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> DATAMSG.rand_hdr(self)</span><br><span> self.rssi = self.rand_rssi()</span><br><span> self.toa256 = self.rand_toa256()</span><br><span>@@ -672,8 +690,9 @@</span><br><span> # C/I: Carrier-to-Interference ratio</span><br><span> self.ci = random.randint(self.CI_MIN, self.CI_MAX)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates human-readable header description</span><br><span> def desc_hdr(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate human-readable header description. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Describe the common part</span><br><span> result = DATAMSG.desc_hdr(self)</span><br><span> </span><br><span>@@ -699,8 +718,9 @@</span><br><span> # Strip useless whitespace and return</span><br><span> return result.strip()</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Encodes Modulation and Training Sequence info</span><br><span> def gen_mts(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Encode Modulation and Training Sequence info. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # IDLE / nope indication has no MTS info</span><br><span> if self.nope_ind:</span><br><span> return self.NOPE_IND</span><br><span>@@ -714,8 +734,9 @@</span><br><span> </span><br><span> return mts</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Parses Modulation and Training Sequence info</span><br><span> def parse_mts(self, mts):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Parse Modulation and Training Sequence info. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # IDLE / nope indication has no MTS info</span><br><span> self.nope_ind = (mts & self.NOPE_IND) > 0</span><br><span> if self.nope_ind:</span><br><span>@@ -738,8 +759,9 @@</span><br><span> self.mod_type = Modulation.ModGMSK</span><br><span> self.tsc_set = mts & 0b11</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates message specific header part</span><br><span> def gen_hdr(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate message specific header part. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Allocate an empty byte-array</span><br><span> buf = bytearray()</span><br><span> </span><br><span>@@ -760,8 +782,9 @@</span><br><span> </span><br><span> return buf</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Parses message specific header part</span><br><span> def parse_hdr(self, hdr):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Parse message specific header part. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Parse RSSI</span><br><span> self.rssi = -(hdr[5])</span><br><span> </span><br><span>@@ -775,16 +798,18 @@</span><br><span> # C/I: Carrier-to-Interference ratio (in centiBels)</span><br><span> self.ci = struct.unpack(">h", hdr[9:11])[0]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generates message specific burst</span><br><span> def gen_burst(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate message specific burst. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Convert soft-bits to unsigned soft-bits</span><br><span> burst_usbits = self.sbit2usbit(self.burst)</span><br><span> </span><br><span> # Encode to bytes</span><br><span> return bytearray(burst_usbits)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Parses message specific burst for header version 0</span><br><span> def _parse_burst_v0(self, burst):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Parse message specific burst for header version 0. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> bl = len(burst)</span><br><span> </span><br><span> # We need to guess modulation by the length of burst</span><br><span>@@ -798,8 +823,9 @@</span><br><span> </span><br><span> return burst[:self.mod_type.bl]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Parses message specific burst</span><br><span> def parse_burst(self, burst):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Parse message specific burst. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> burst = list(burst)</span><br><span> </span><br><span> if self.ver == 0x00:</span><br><span>@@ -808,15 +834,17 @@</span><br><span> # Convert unsigned soft-bits to soft-bits</span><br><span> self.burst = self.usbit2sbit(burst)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Generate a random message specific burst</span><br><span> def rand_burst(self, length = None):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Generate a random message specific burst. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> if length is None:</span><br><span> length = self.mod_type.bl</span><br><span> </span><br><span> self.burst = [random.randint(-127, 127) for _ in range(length)]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- # Transforms this message to L12TRX message</span><br><span> def gen_l12trx(self, ver = None):</span><br><span style="color: hsl(120, 100%, 40%);">+ ''' Transform this message to L12TRX message. '''</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> # Allocate a new message</span><br><span> msg = DATAMSG_L12TRX(fn = self.fn, tn = self.tn,</span><br><span> ver = self.ver if ver is None else ver)</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmocom-bb/+/23132">change 23132</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmocom-bb/+/23132"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: osmocom-bb </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: I856b54fd1baca4ae0edd2aa59be6a76372cef667 </div>
<div style="display:none"> Gerrit-Change-Number: 23132 </div>
<div style="display:none"> Gerrit-PatchSet: 3 </div>
<div style="display:none"> Gerrit-Owner: fixeria <vyanitskiy@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: Jenkins Builder </div>
<div style="display:none"> Gerrit-Reviewer: fixeria <vyanitskiy@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: laforge <laforge@osmocom.org> </div>
<div style="display:none"> Gerrit-Reviewer: pespin <pespin@sysmocom.de> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>