Editor: Byte Array Messages
Creating a Byte Array Message
Similar to other messages, a Byte Array message is a Nominal Systems message type that wraps around some raw binary byte data. It is useful for customizing particular packets with ordered sets of data. Provided that the user can configure the bytes in a particular and known way, this can be used to send through packets of information in an optimized and manageable way. This can be created by calling the Create Byte Array Message function in Unreal.
To create a new Byte Array list of a particular length, either use the Unreal method of creating a new array or call the Create Byte Array function and enter the number of bytes into the function. Connect the array output to the make payload.
Writing Bytes
Bytes can be written to the byte array using the Byte Array helper functions. However, these must be done before submitting the bytes to the message. Several functions correctly convert particular types of data to bytes.
Each function contains a Source, which is a reference to the byte array (not a copy of the array), an Offset which indicates the starting byte index to write the data to and a Value, which is the value of the particular type to write the data. For example, writing a 4-byte integer and an 8-byte string to the array would look like the following:
The following table shows how many bytes each type contains:
| Type | Bytes | Minimum Value | Maximum Value |
|---|---|---|---|
| Bool | 1 | False | True |
| Float 32 | 4 | \(-3.4028235 × 10^{38}\) | $ 3.4028235 × 10^{38}$ |
| Float 64 | 8 | $ -1.7976931348623157 × 10^{308}$ | \(1.7976931348623157 × 10^{308}\) |
| Int 8 (Signed) | 1 | \(-128\) | \(127\) |
| Int 8 (Unsigned) | 1 | \(0\) | \(255\) |
| Int 16 (Signed) | 2 | \(-32,768\) | \(32,767\) |
| Int 16 (Unsigned) | 2 | \(0\) | \(65,535\) |
| Int 32 (Signed) | 4 | \(-2,147,483,648\) | $ 2,147,483,647$ |
| Int 32 (Unsigned) | 4 | \(0\) | \(4,294,967,295\) |
| Int 64 (Signed) | 8 | \(-9,223,372,036,854,775,808\) | \(9,223,372,036,854,775,807\) |
| Int 64 (Unsigned) | 8 | \(0\) | \(18,446,744,073,709,551,615\) |
| String UTF8 | 1 per character (+1 for Null character) | ||
| String UTF16 | 2 per character (+2 for Null character) |
Reading Bytes
Reading byte array data can be done in the same way. The order of the data within the packet must be known, with the correct number of bytes for each type. In the same case as above, if there was a Signed Int32 and a UTF8 string within the data, then this can be read from the data using one of the functions.
Each function contains a reference to the Source array with the bytes. It also contains an Offset, which is the index to start reading the data. The Return Value will be of the type specified by the function.
Transmitting Bytes
Once the bytes have been written to the array, the byte array can be transmitted over the TT&C data network in the same way that any other message can be transmitted. This can be done using a transmitter Transmit Message function and passing in the message ID of the byte array message that was created.
From there, bytes can be read on the receiver (provided that the connection is valid and the keys match) and the reading byte functions can be used to decompose the packets back into the individual data points.
Warning
Although the byte array sending is optimized, the number of bytes sent across the network will be slightly more than the number of bytes written to by the user. This will include the packet header information which is used to ensure that the byte data is correctly parsed and no packets are lost over the network. The header is a fixed byte count and will not change with the number of raw bytes written to the message.