Crate spinel_pack

This Rust crate allows you to easily and safely serialize/deserialize data structures into the byte format specified in section 3 of the Spinel Protocol Documentation. This documentation assumes some familiarity with that documentation. The behavior of this crate was inspired by the spinel_datatype_pack/spinel_datatype_unpack methods from OpenThread.

Key Features

• Ability to deserialize to borrowed types (like &str) in addition to owned types.
• Convenient attribute macro (#[spinel_packed("...")]) for automatically implementing pack/unpack traits on datatypes, including structs with borrowed references and nested Spinel data types.
• Convenient in-line macros (spinel_read!(...)/spinel_write!(...)) for parsing arbitrary Spinel data immediately in place without the need to define new types.
• All macros check the format strings against the types being serialized/deserialized at compile-time, generating compiler errors whenever there is a mismatch.

Packing/Serialization

Serialization is performed via two traits:

• TryPack for serializing to the natural Spinel byte format for the given type. The key method on the trait is try_pack().
• TryPackAs<MarkerType> for serializing to one of the specific Spinel format types. Since this trait is generic, a given type can have multiple implementations of this trait for serializing to the byte format specified by MarkerType. The key method on the trait is try_pack_as().

The TryPack/TryPackAs traits operate on types that implement std::io::Write, which includes Vec<u8> and &mut&mut[u8].

Unpacking/Deserialization

Deserialization is performed via three traits:

• TryUnpack for deserializing bytes into an instance of the associated type Self::Unpacked (which is usually Self), inferring the byte format from the type. This trait supports deserializing to both borrowed types (like &str) and owned types (like String), and thus has a lifetime parameter. The key method on the trait is try_unpack().
• TryUnpackAs<MarkerType> for deserializing a spinel field that is encoded as a MarkerType into an instance of the associated type Self::Unpacked (which is usually Self). This trait supports deserializing to both borrowed types (like &str) and owned types (like String), and thus has a lifetime parameter. The key method on the trait is try_unpack_as().
• TryOwnedUnpack, which is similar to TryUnpack except that it supports owned types only (like String). The key method on the trait is try_owned_unpack().

The TryUnpack/TryOwnedUnpack traits operate on byte slices (&[u8]) and byte slice iterators (std::slice::Iter<u8>).

Supported Primitive Types

This crate supports the following raw Spinel types:

Char	Name	Type	Marker Type (if different)
.	VOID	()
b	BOOL	bool
C	UINT8	u8
c	INT8	i8
S	UINT16	u16
s	INT16	i16
L	UINT32	u32
l	INT32	i32
i	UINT_PACKED	u32	SpinelUint
6	IPv6ADDR	std::net::Ipv6Addr
E	EUI64	EUI64
e	EUI48	EUI48
D	DATA	&[u8]/Vec<u8>	[u8]
d	DATA_WLEN	&[u8]/Vec<u8>	SpinelDataWlen
U	UTF8	&str/String	str

The Spinel struct (t(...)) and array (A(...)) types are not directly supported and will result in a compiler error if used in a Spinel format string. However, you can emulate the behavior of spinel structs by replacing the t(...) with a d and using another Spinel datatype (like one created with the spinel_packed attribute) instead of &[u8] or Vec<u8>.

How Format Strings Work

The macro spinel_write!(...) can be used to directly unpack Spinel-encoded data into individual fields, with the encoded type being defined by a format string. This macro will parse the format string, associating each character in the string with a specific Marker Type and field argument. For each of the fields in the format, the macro will make a call into TryPackAs<MarkerType>::try_pack_as(...) for the given field’s argument. If there is no implementation of TryPackAs<MarkerType> for the type of the field’s argument, a compile-time error is generated.

Examples

Struct example:

use spinel_pack::prelude::*;

#[spinel_packed("CiiLUE")]
#[derive(Debug, Eq, PartialEq)]
pub struct SomePackedData<'a> {
    foo: u8,
    bar: u32,
    blah: u32,
    bleh: u32,
    name: &'a str,
    addr: spinel_pack::EUI64,
}

Packing into a new Vec:

let data = SomePackedData {
    foo: 10,
    bar: 20,
    blah: 30,
    bleh: 40,
    name: "This is a string",
    addr: spinel_pack::EUI64([0,0,0,0,0,0,0,0]),
};

let packed: Vec<u8> = data.try_packed()?;

Packing into an existing array:

let data = SomePackedData {
    foo: 10,
    bar: 20,
    blah: 30,
    bleh: 40,
    name: "This is a string",
    addr: spinel_pack::EUI64([0,0,0,0,0,0,0,0]),
};

let mut bytes = [0u8; 500];
let length = data.try_pack(&mut &mut bytes[..])?;

Unpacking:

let bytes: &[u8] = &[0x01, 0x02, 0x03, 0xef, 0xbe, 0xad, 0xde, 0x31, 0x32, 0x33, 0x00, 0x02,
                     0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff];

let data = SomePackedData::try_unpack(&mut bytes.iter())?;

assert_eq!(data.foo, 1);
assert_eq!(data.bar, 2);
assert_eq!(data.blah, 3);
assert_eq!(data.bleh, 0xdeadbeef);
assert_eq!(data.name, "123");
assert_eq!(data.addr, spinel_pack::EUI64([0x02,0xff,0xff,0xff,0xff,0xff,0xff,0xff]));

Spinel packed structs can be nested:

#[spinel_packed("idU")]
#[derive(Debug, Eq, PartialEq)]
pub struct SomeNestedData<'a> {
    foo: u32,
    test_struct_1: SomePackedData<'a>,
    name: String,
}

Each field of a struct must have an associated format type indicator:

#[spinel_packed("i")]
#[derive(Debug, Eq, PartialEq)]
pub struct SomePackedData {
    foo: u32,
    data: &'a [u8], // Compiler error, no format type
}

Likewise, each format type indicator must have a field:

#[spinel_packed("id")]
#[derive(Debug, Eq, PartialEq)]
pub struct SomePackedData {
    foo: u32,
} // Compiler error, missing field for 'd'

#use spinel_pack::prelude::*;
#[spinel_packed("id")]
#[derive(Debug, Eq, PartialEq)]
pub struct SomePackedData; // Compiler error, no fields at all

Using spinel_write!():

let mut target: Vec<u8> = vec![];

spinel_write!(&mut target, "isc", 1, 2, 3)
    .expect("spinel_write failed");

assert_eq!(target, vec![1u8,2u8,0u8,3u8]);

Using spinel_read!():

// The data to parse.
let bytes: &[u8] = &[
    0x01, 0x02, 0x83, 0x03, 0xef, 0xbe, 0xad, 0xde,
    0x31, 0x32, 0x33, 0x00, 0x02, 0xf1, 0xf2, 0xf3,
    0xf4, 0xf5, 0xf6, 0xf7,
];

// The variables that we will place
// the parsed values into. Note that
// currently these need to be initialized
// before they can be used with `spinel_read`.
let mut foo: u8 = 0;
let mut bar: u32 = 0;
let mut blah: u32 = 0;
let mut bleh: u32 = 0;
let mut name: String = Default::default();
let mut addr: spinel_pack::EUI64 = Default::default();

// Parse the data.
spinel_read!(&mut bytes.iter(), "CiiLUE", foo, bar, blah, bleh, name, addr)
    .expect("spinel_read failed");

// Verify that the variables match
// the values we expect.
assert_eq!(foo, 1);
assert_eq!(bar, 2);
assert_eq!(blah, 387);
assert_eq!(bleh, 0xdeadbeef);
assert_eq!(name, "123");
assert_eq!(addr, spinel_pack::EUI64([0x02, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7]));

Modules

• prelude
  Prelude module intended for blanket inclusion to make the crate easier to use.

Macros

• impl_try_unpack_for_owned
  Provides an automatic implementation of TryUnpack when wrapped around an implementation of TryOwnedUnpack.
• spinel_read
  In-line proc macro for parsing spinel-formatted data fields from a byte slice iterator.
• spinel_write
  In-line proc macro for writing spinel-formatted data fields to a type implementing std::io::Write.
• spinel_write_len
  In-line proc macro for determining the written length of spinel-formatted data fields.

Structs

• EUI48
  Data type representing a EUI48 address.
• EUI64
  Data type representing a EUI64 address.

Enums

• SpinelDataWlen
  Marker type used to specify data fields that are prepended with its length.
• SpinelUint
  Marker type used to specify integers encoded with Spinel’s variable-length unsigned integer encoding.
• UnpackingError
  Error type for unpacking operations.

Traits

• SpinelFixedLen
  Marker trait for types which always serialize to the same length.
• TryOwnedUnpack
  Trait for unpacking only into owned types, like Vec<u8> or String.
• TryPack
  Trait implemented by data types that support being serialized to a spinel-based byte encoding.
• TryPackAs
  Trait implemented by data types that support being serialized to a specific spinel-based byte encoding, based on the marker type.
• TryUnpack
  Trait for unpacking a spinel-encoded buffer to a specific type.
• TryUnpackAs
  Trait for unpacking a spinel-encoded buffer to a specific type when the field type is known.

Attribute Macros

• spinel_packed
  Attribute macro which takes a Spinel format string as an argument and automatically defines the TryPack/TryUnpack traits for the given struct.