Moto Mods Firmware: Raw Protocol

Overview

The Raw class provides a direct channel between the Moto Mod’s Android application and the firmware itself.  At its base, it provides two way asynchronous transport.  This is the primary mechanism to implement custom behavior which will require you write a peer application.  The Moto Mods platform has no default handling of the Raw protocol, it merely provides access to the data pipe.

Any logic or higher level protocols are up to you, the developer.  When handling Raw messages, care must be taken to ensure a response is delivered within one second.  If this cannot be achieved, your implementation should separate the Raw thread from your main processing thread.

Related Links


Hardware Manifest

Hardware Manifest files reside in apps/greybus-utils/manifests, one should be created for your unique project.

0xFE is the identifier for the Raw protocol.

Two entries are necessary for Raw, one for the Interface and one for the Bundle.

; RAW interface on CPort XX
[cport-descriptor XX]
bundle = YY
protocol = 0xfe

; RAW Bundle YY
[bundle-descriptor YY]
class = 0xfe

XX shall be a unique integer (within your hardware manifest) defining which CPort is used for Raw.

YY shall be a unique integer (within your hardware manifest) which Bundle the Raw CPort is a member of.


Implementation

Files

nuttx/include/nuttx/device_raw.h

This file defines the device_raw_type_ops structure and provides the glue to the Greybus Raw channel.

nuttx/configs/hdk/muc/src/stm32_modsraw.c

This file provides the starting point for your Raw development. It should be copied into nuttx/configs/PROJECT/src for your specific Project and modified.

Callbacks

raw_send_callback

The raw_send_callback method is provided to your Raw device driver upon registration. Your firmware will use this function pointer to send Raw data TO the Moto Z.

int (*raw_send_callback)(struct device *dev, uint32_t len, uint8_t data[])
Parameters
dev Matches dev passed to the probe function
len Length in bytes of data to send (8192 bytes max)
data Byte array of data
Returns
int 0 on success, negative errno on error

Structures

device_raw_type_ops

The device_raw_type_ops structure contains pointers to your specific method implementations and is used in driver registration.

struct device_raw_type_ops {
    int (*recv)(struct device *dev, uint32_t len, uint8_t data[]);
    int (*register_callback)(struct device *dev, raw_send_callback cb);
    int (*unregister_callback)(struct device *dev);
};

Message Size

The Raw channel supports messages up to 8K in size. Be aware that using larger message sizes will likely require increases in stack and buffer sizes, impacting the MuC’s RAM usage.


Methods

recv

You implement the recv method to be called when data is received FROM the Moto Z.

int (*recv)(struct device *dev, uint32_t len, uint8_t data[])
Parameters
dev Matches dev passed to the probe function
len Length in bytes of data received (8192 bytes max)
data Byte array of data
Returns
int 0 on success, negative errno on error

register_callback

You implement the register_callback method to be called after the initial driver probe call to notify the driver of the method call used for sending Raw data.

int (*register_callback)(struct device *dev, raw_send_callback cb)
Parameters
dev Matches dev passed to the probe function
cb Send function pointer
Returns
int 0 on success, negative errno on error

unregister_callback

You implement the unregister_callback method to be called when sending data is no longer valid. The cached raw_send_callback pointer should be set to NULL when this is called.

It is possible to have your recv method called even after the unregister_callback. Your firmware must handle this gracefully.

int (*unregister_callback)(struct device *dev)
Parameters
dev Matches dev passed to the probe function
Returns
int 0 on success, negative errno on error

Usage

When communicating with your APK, the below diagram shows a Command initiated via Raw from your APK and responded to by your firmware.

For an end-to-end example of using the Raw protocol, see the Temperature Sensor Personality Card (example coming soon).