PacketBuffer#

Overview#

The MicroBitRadio class provides direct micro:bit to micro:bit communication.

It is often beneficial in both wired and wireless communication protocols to send and receive data in a raw format, viewed as an ordered sequence of bytes.

This class provides a basic set of functions for the creation, manipulation and accessing of a managed type for byte arrays used to hold network data packets.

Note

This is a managed type. This means that it will automatically use and release memory as needed. There is no need for you to explicitly free or release memory when your done - the memory will be freed as soon as the last piece of code stops using the data.

Creating PacketBuffers#

PacketBuffers are simple to create - just create them like a variable, and provide the size (in bytes) of the buffer you want to create.

PacketBuffer b(16);

Alternatively, if you already have an array of bytes allocated, then you can simply refer to that using a slightly different form:

uint8_t data[16];
PacketBuffer b(data,16);

Manipulating PacketBuffers#

Once created, the data inside PacketBuffers can be freely changed at any time. The simplest way to do this is through the array operators [ and ].

You can read or write bytes to the buffer by simply dereferencing it with square bracket.

For example: to create, set and send a PacketBuffer on the micro:bit radio, you could do the following:

PacketBuffer b(2);
b[0] = 255;
b[1] = 10;

uBit.radio.datagram.send(b);

PacketBuffers can also be assigned a value:

PacketBuffer b;
b = uBit.radio.datagram.recv();

If you need more granular access, the getBytes function provides direct access to the memory buffer, presented as a byte array:

PacketBuffer b(16);
uint8_t *buf = b.getBytes();

memcpy(buf, "HI", 2);

Finally, it is also possible to extract the received signal strength of a packet from a PacketBuffer.

This can provide both a rough indication of the reliability of the link, and a crude but moderately effective mechanism to estimate the distance between two micro:bits.

PacketBuffer b;
b = uBit.radio.datagram.recv();

uBit.display.scroll(b.getRSSI());

API#

Constructor#


ManagedString(
StringData *
ptr)#

Description#

Constructor. Create a managed string from a specially prepared string literal.

Parameters#

StringData *
ptr - The literal - first two bytes should be 0xff, then the length in little endian, then the literal. The literal has to be 4-byte aligned.

Example#
 static const char hello[] __attribute__ ((aligned (4))) = "\xff\xff\x05\x00" "Hello"; 
 ManagedString s((StringData*)(void*)hello); 

leakData#


StringData
leakData
()#

Description#

Get current ptr, do not decr() it, and set the current instance to empty string.

This is to be used by specialized runtimes which pass StringData around.

Constructor#


ManagedString(
const char *
str)#

Description#

Constructor.

Create a managed string from a pointer to an 8-bit character buffer.

The buffer is copied to ensure safe memory management (the supplied character buffer may be declared on the stack for instance).

Parameters#

const char *
str - The character array on which to base the new ManagedString .

Example#
 ManagedString s("abcdefg"); 


ManagedString(
const int
value)#

Description#

Constructor.

Create a managed string from a given integer.

Parameters#

const int
value - The integer from which to create the ManagedString .

Example#
 ManagedString s(20); 


ManagedString(
const char
value)#

Description#

Constructor. Create a managed string from a given char.

Parameters#

const char
value - The character from which to create the ManagedString .

Example#
 ManagedString s('a'); 


ManagedString(
PacketBuffer
buffer)#

Description#

Constructor. Create a ManagedString from a PacketBuffer . All bytes in the PacketBuffer are added to the ManagedString .

Parameters#

PacketBuffer
buffer - The PacktBuffer from which to create the ManagedString .

Example#
 ManagedString s = radio.datagram.recv(); 


ManagedString(
const char *
str,
const int16_t
length)#

Description#

Constructor. Create a ManagedString from a pointer to an 8-bit character buffer of a given length.

The buffer is copied to ensure sane memory management (the supplied character buffer may be declared on the stack for instance).

Parameters#

const char *
str - The character array on which to base the new ManagedString .

const int16_t
length - The length of the character array

Example#
 ManagedString s("abcdefg",7); 


ManagedString(
const ManagedString &
s)#

Description#

Copy constructor. Makes a new ManagedString identical to the one supplied.

Shares the character buffer and reference count with the supplied ManagedString .

Parameters#

const ManagedString &
s - The ManagedString to copy.

Example#
 ManagedString s("abcdefg"); 
 ManagedString p(s); 


ManagedString()#

Description#

Default constructor.

Create an empty ManagedString .

Example#
 ManagedString s(); 

operator=#


ManagedString
operator=
(
const ManagedString &
s)#

Description#

Copy assign operation.

Called when one ManagedString is assigned the value of another.

If the ManagedString being assigned is already referring to a character buffer, decrement the reference count and free up the buffer as necessary.

Then, update our character buffer to refer to that of the supplied ManagedString , and increase its reference count.

Parameters#

const ManagedString &
s - The ManagedString to copy.

Example#
 ManagedString s("abcd"); 
 ManagedString p("efgh"); 
 p = s // p now points to s, s' ref is incremented 

operator==#


bool
operator==
(
const ManagedString &
s)#

Description#

Equality operation.

Called when one ManagedString is tested to be equal to another using the ‘==’ operator.

Parameters#

const ManagedString &
s - The ManagedString to test ourselves against.

Returns#

true if this ManagedString is identical to the one supplied, false otherwise.

Example#
 MicroBitDisplay display; 
 ManagedString s("abcd"); 
 ManagedString p("efgh"); 

 if(p == s) 
 display.scroll("We are the same!"); 
 else 
 display.scroll("We are different!"); //p is not equal to s - this will be called 

operator<#


bool
operator<
(
const ManagedString &
s)#

Description#

Inequality operation.

Called when one ManagedString is tested to be less than another using the ‘<’ operator.

Parameters#

const ManagedString &
s - The ManagedString to test ourselves against.

Returns#

true if this ManagedString is alphabetically less than to the one supplied, false otherwise.

Example#
 MicroBitDisplay display; 
 ManagedString s("a"); 
 ManagedString p("b"); 

 if(s < p) 
 display.scroll("a is before b!"); //a is before b 
 else 
 display.scroll("b is before a!"); 

operator>#


bool
operator>
(
const ManagedString &
s)#

Description#

Inequality operation.

Called when one ManagedString is tested to be greater than another using the ‘>’ operator.

Parameters#

const ManagedString &
s - The ManagedString to test ourselves against.

Returns#

true if this ManagedString is alphabetically greater than to the one supplied, false otherwise.

Example#
 MicroBitDisplay display; 
 ManagedString s("a"); 
 ManagedString p("b"); 

 if(p>a) 
 display.scroll("b is after a!"); //b is after a 
 else 
 display.scroll("a is after b!"); 

substring#


ManagedString
substring
(
int16_t
start,
int16_t
length)#

Description#

Extracts a ManagedString from this string, at the position provided.

Parameters#

int16_t
start - The index of the first character to extract, indexed from zero.

int16_t
length - The number of characters to extract from the start position

Returns#

a ManagedString representing the requested substring.

Example#
 MicroBitDisplay display; 
 ManagedString s("abcdefg"); 

 display.scroll(s.substring(0,2)) // displays "ab" 

charAt#


char
charAt
(
int16_t
index)#

Description#

Provides a character value at a given position in the string, indexed from zero.

Parameters#

int16_t
index - The position of the character to return.

Returns#

the character at posisiton index, zero if index is invalid.

Example#
 MicroBitDisplay display; 
 ManagedString s("abcd"); 

 display.scroll(s.charAt(1)) // scrolls "b" 

toCharArray#


const char *
toCharArray
()#

Description#

Provides an immutable 8 bit wide character buffer representing this string.

Returns#

a pointer to the character buffer.

length#


int16_t
length
()#

Description#

Determines the length of this ManagedString in characters.

Returns#

the length of the string in characters.

Example#
 MicroBitDisplay display; 
 ManagedString s("abcd"); 

 display.scroll(s.length()) // scrolls "4"