egse.bits
This module contains a number of convenience functions to work with bits, bytes and integers.
Functions:
| Name | Description |
|---|---|
beautify_binary |
Returns a binary representation of the given value. The bits are presented |
bit_set |
Return True if the bit is set. |
bits_set |
Return True if all the bits are set. |
clear_bit |
Set bit to 0 for the given value. |
clear_bits |
Set the given bits in value to 0. |
crc_calc |
Calculate the checksum for (part of) the data. |
extract_bits |
Extracts a specified number of bits from an integer starting at a given position. |
humanize_bytes |
Represents the size |
s16 |
Return the signed equivalent of a hex or binary number. |
s32 |
Return the signed equivalent of a hex or binary number. |
set_bit |
Set bit to 1 for the given value. |
set_bits |
Set the given bits in value to 1. |
toggle_bit |
Toggle the bit in the given value. |
beautify_binary(value, sep=' ', group=8, prefix='', size=0)
Returns a binary representation of the given value. The bits are presented
in groups of 8 bits for clarity by default (can be changed with the group keyword).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
int
|
the value to beautify |
required |
sep
|
str
|
the separator character to be used, default is a space |
' '
|
group
|
int
|
the number of bits to group together, default is 8 |
8
|
prefix
|
str
|
a string to prefix the result, default is '' |
''
|
size
|
int
|
number of digits |
0
|
Returns:
| Type | Description |
|---|---|
str
|
a binary string representation. |
Examples:
>>> status = 2**14 + 2**7
>>> assert beautify_binary(status) == "01000000 10000000"
bit_set(value, bit)
Return True if the bit is set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
int
|
the value to check |
required |
bit
|
int
|
the index of the bit to check, starting from 0 at the LSB |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if the bit is set (1). |
bits_set(value, *args)
Return True if all the bits are set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
int
|
the value to check |
required |
args
|
a set of indices of the bits to check, starting from 0 at the LSB |
()
|
Returns:
| Type | Description |
|---|---|
bool
|
True if all the bits are set (1). |
Examples:
>>> assert bits_set(0b0101_0000_1011, [0, 1, 3, 8, 10])
>>> assert bits_set(0b0101_0000_1011, [3, 8])
>>> assert not bits_set(0b0101_0000_1011, [1, 2, 3])
clear_bit(value, bit)
Set bit to 0 for the given value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
int
|
the integer value that needs a bit set or unset |
required |
bit
|
int
|
the index of the bit to set/unset, starting from 0 at the LSB |
required |
Returns:
| Type | Description |
|---|---|
int
|
the changed value. |
clear_bits(value, bits)
Set the given bits in value to 0.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
int
|
the value where the given bits shall be changed |
required |
bits
|
tuple
|
a tuple with start and stop bits |
required |
Returns:
| Type | Description |
|---|---|
int
|
the changed value |
crc_calc(data, start, len)
Calculate the checksum for (part of) the data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
the data for which the checksum needs to be calculated |
required | |
start
|
int
|
offset into the data array [byte] |
required |
len
|
int
|
number of bytes to incorporate into the calculation |
required |
Returns:
| Type | Description |
|---|---|
int
|
the calculated checksum. |
Reference
The description of the CRC calculation for RMAP is given in the ECSS document Space Engineering: SpaceWire - Remote Memory Access Protocol, section A.3 on page 80 [ECSS‐E‐ST‐50‐52C].
extract_bits(value, start_position, num_bits)
Extracts a specified number of bits from an integer starting at a given position.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
int
|
The input integer. |
required |
start_position
|
int
|
The starting bit position (0-based index). |
required |
num_bits
|
int
|
The number of bits to extract. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
int |
int
|
The extracted bits as an integer. |
humanize_bytes(n, base=2, precision=3)
Represents the size n in human readable form, i.e. as byte, KiB, MiB, GiB, ...
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
number of byte |
required |
base
|
(int, str)
|
binary (2) or decimal (10) |
2
|
precision
|
int
|
the number of decimal places [default=3] |
3
|
Returns:
| Type | Description |
|---|---|
str
|
a human readable size, like 512 byte or 2.300 TiB |
Raises:
| Type | Description |
|---|---|
ValueError
|
when base is different from 2 (binary) or 10 (decimal). |
Examples:
>>> assert humanize_bytes(55) == "55 bytes"
>>> assert humanize_bytes(1024) == "1.000 KiB"
>>> assert humanize_bytes(1000, base=10) == "1.000 kB"
>>> assert humanize_bytes(1000000000) == '953.674 MiB'
>>> assert humanize_bytes(1000000000, base=10) == '1.000 GB'
>>> assert humanize_bytes(1073741824) == '1.000 GiB'
>>> assert humanize_bytes(1024**5 - 1, precision=0) == '1024 TiB'
Note
Please note that, by default, I use the IEC standard (International Engineering Consortium)
which is in base=2 (binary), i.e. 1024 bytes = 1.0 KiB. If you need SI units (International
System of Units), you need to specify base=10 (decimal), i.e. 1000 bytes = 1.0 kB.
s16(value)
Return the signed equivalent of a hex or binary number.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
int
|
an integer value. |
required |
Returns:
| Type | Description |
|---|---|
int
|
The negative equivalent of a twos-complement binary number. |
Examples:
Since integers in Python are objects and stored in a variable number of bits, Python doesn't know the concept of twos-complement for negative integers. For example, this 16-bit number
>>> 0b1000_0000_0001_0001
32785
which in twos-complement is actually a negative value:
>>> s16(0b1000_0000_0001_0001)
-32751
The 'bin()' fuction will return a strange representation of this number:
>>> bin(-32751)
'-0b111111111101111'
when we however mask the value we get:
>>> bin(-32751 & 0b1111_1111_1111_1111)
'0b1000000000010001'
s32(value)
Return the signed equivalent of a hex or binary number.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
int
|
an integer value. |
required |
Returns:
| Type | Description |
|---|---|
|
The negative equivalent of a twos-complement binary number. |
Examples:
Since integers in Python are objects and stored in a variable number of bits, Python doesn't know the concept of twos-complement for negative integers. For example, this 32-bit number
>>> 0b1000_0000_0000_0000_0000_0000_0001_0001
2147483665
which in twos-complement is actually a negative value:
>>> s32(0b1000_0000_0000_0000_0000_0000_0001_0001)
-2147483631
set_bit(value, bit)
Set bit to 1 for the given value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
int
|
the integer value that needs a bit set or unset |
required |
bit
|
int
|
the index of the bit to set/unset, starting from 0 at the LSB |
required |
Returns:
| Type | Description |
|---|---|
int
|
the changed value. |
set_bits(value, bits)
Set the given bits in value to 1.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
int
|
the value where the given bits shall be changed |
required |
bits
|
tuple
|
a tuple with start and stop bits |
required |
Returns:
| Type | Description |
|---|---|
int
|
the changed value. |
toggle_bit(value, bit)
Toggle the bit in the given value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
int
|
the integer value that needs a bit toggled |
required |
bit
|
int
|
the index of the bit to toggle, starting from 0 at the LSB |
required |
Returns:
| Type | Description |
|---|---|
int
|
the changed value. |