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" 

---