Reference Manual


Template / Scramble Protocol Frame

This command should only be required in very rare cases. Usually ExtractBitField is a better and much more simpler option.

Using this command, the bits of the last generated Bytes can be scrambled/inverted in any fashion. The main steps of this command are:

  1. Determine the data that shall be scrambled. Either the last Len bytes are used, or (if Len is 0xFF) all bytes from the last marker (see Mark command) to the end are used. This data is used as source data and will be replaced.
  2. Split the resulting block into sub-blocks, that all are of length SourceSubBlockBits. If Len * 8 is not multiple of SourceSubBlockBits the remaining bits in the source data are ignored by default. Alternatively the ScrambleOptions can be used to set "PadZero". In this case the remaining bits of the source data are extended by 0-bits until the length of the remaining block is SourceSubBlockBits and thus can be processed.
  3. Every source block is scrambled by generating a destination block. This destination block is of the same size as the BitMap array. BitMap specifies a mapping of source bits to destination bits. This mapping is applied to every source block and results in a corresponding destination block
  4. The scrambled destination blocks are concatenated again. If the total number of bits in all destination blocks is not a multiple of 8, padding zero bits are appended, until the number of bits is exactly a multiple of 8.
  5. The filters specified in Filters are applied to the resulting content.

The most regular use case of this command is cutting a bitfield out of the source data without the requirement of repetitions. The following command shows a sample, that cuts a field of 4 bits starting at bit index 6 from the source data and converts it to a 4 digit ASCII decimal number.

Sample
{optionally some data before scramble}
Mark
{template to be scrambled}
Scramble
0xFF 'scramble all data between Mark and Scramble'
NoRepeat 'Do a simple scramble without multiple blocks'
16 'scramble the first 16 bits of {variable-data}'
8 'the scrambled data should be a multiple of 8!'
0x7F 0x7F 0x7F 0x7F 6 7 8 9 '4 leading zeros, then bytes 6-9 of source data'
Bin2Bcd|Unpack|Bin2Ascii 'convert data to ASCII decimal'

Properties

Format

Name Type/Size Description
Len Integer (8 bits) Specifies the number of bytes before the Scramble command, that shall be scrambled. If this value is 0xFF, all bytes between the last Mark (or the beginning of the template, if no Mark is available) and this Scramble are taken.
ScrambleOptions Bit mask (8 bits) These keywords can be used to parametrize the way the scambler (see Scramble command) splits data into sub-blocks.
RFU Integer (bit mask area 0xF8) Zero padding
NoRepeat Boolean (bit 0x04)

Instead of splitting the source data into multiple sub-blocks, only the first sub-block is used for further processing. The other subblocks are thrown away.

Template:
>> 0x55 0xAA Scramble 2 NoRepeat 7 4 0x00 0x81 0x7F 0xFF NoFilter
one7bits Sub-Block (in binary representation):
>> 0101010
PadZero Boolean (bit 0x02)

If the source data's length * 8 is not a multiple of the length of the sub-blocks usually the residual is thrown away. With this option the residual is filled up with zeros and added to the list of sub-blocks to process

Template:
>> 0x55 0xAA Scramble 2 PadZero 7 4 0x00 0x81 0x7F 0xFF NoFilter
7bits Sub-Blocks including filled up residual (in binary representation):
>> 0101010 1101010 10[00000]
AlignRight Boolean (bit 0x01)

If the source data's length * 8 is not a multiple of the length of the sub-blocks usually the residual is at the end of the source data. With this option the residual is at the beginning of the source data.

Template:
>> 0x55 0xAA Scramble 2 AlignRight 7 4 0x00 0x81 0x7F 0xFF NoFilter
2bit leading residual + 7bits Sub-Blocks (in binary representation):
>> (01) 0101011 0101010
SourceSubBlockBits Integer (8 bits) The number of bits that form a subblock of the source block.
Length of BitMap Integer (8 bits) Number of elements in the BitMap array
BitMap Array This array contains mapping, that maps every bits in the destination block to a bit in the source block or a constant value.
- Bit mask (8 bits) -
Invert Boolean (bit 0x80) If this flag is set, the current bit in the destination block will be inverted.
SrcBitPos Integer (bit mask area 0x7F)

The Index of a bit in the source block that shall be copied into the current position of the destination block. The index starts at the leftmost position of the source block (and assumes that the bytes in the source block are MSB encoded.

If this value is 0x7F instead of taking a bit in the source block a constant 0-bit will be inserted (except Inverted is True; in this case a constant 1-bit will be inserted)

Filters Bit mask (8 bits)

For every of these filter bits, a specific data conversion mechanism is specified. This mechanism is applied to a TemplateCommand if the filterbit is set.

The activated filters are applied ordered by there value. Starting with the smallest value.

BcdToBin Boolean (bit 0x80)

Converts a BCD Number (must only contain nibbles 0-9, not A-F) to a binary number. Input and Output data are MSB encoded.

The length of the destination data is the length of the source data (in bytes) multiplied by 0.83048 (and rounded down to the next byte boundary).

Some source data's binary representation is longer than the calculated destination length. If such source data could occur, an additional leading zerobyte has to be inserted in front of the source data 0x12 0x34 => 0x04 0xD2
BinToAscii Boolean (bit 0x40) Convert Binarydata to ASCII by converting the ASCII characters 0x00-0x09 to 0x30-0x39 and 0x0A-0x0F to 0x41-0x49. 0x01 0x0A -> 0x31 0x41
Unpack Boolean (bit 0x20) Splits the high and the low nibble of each byte into two separate bytes, where the high nibble is set to 0. 0x01 CF => 0x00 0x01 0x0C 0x0F
BinToBcd Boolean (bit 0x10)

Converts a binary Number to a BCD encoded number. Input and Output data are MSB encoded.

The length of the destination data is the length of the source data in bytes) multiplied by 1.2041 (and rounded up to the next byte boundary).

This is not exactly the inverse of BcdToBin, since the length may differ. 0x04 0xD2 => 0x12 0x34
SwapNibbles Boolean (bit 0x08) Swap the higher nibble (bits 5-7) of each byte with the lower nibble (bits 0-3). 0x12 0x34 0xEF => 0x21 0x43 0xFE
Pack Boolean (bit 0x04) Merges two Bytes at a time to a single one by removing the leading nibble (which has to be 0) of each byte. 0x03 0x0F -> 0x3F
AsciiToBin Boolean (bit 0x02) Convert ASCII to Binarydata by converting the ASCII characters 0x30-0x39 to 0x00-0x09 and 0x41-0x49 (0x61-0x66) to 0x0A-0x0F. 0x31 0x41 -> 0x01 0x0A
Reverse Boolean (bit 0x01) Swap the first byte with the last one, the second one with the next to last one and so on. 0x12 0x3D 0xEF => 0xEF 0x3D 0x12