fuchsia.lowpan.spinel

PROTOCOLS

DeviceSetup

Defined in fuchsia.lowpan.spinel/spinel.fidl

SetChannel

Request

NameType
channel handle<channel>

Response

NameType
result DeviceSetup_SetChannel_Result

Device

Defined in fuchsia.lowpan.spinel/spinel.fidl

Open

Opens the Spinel connection and performs initialization.

This method will block until the Device is ready to use or an error has been encountered. If an error is indicated, the device is still considered closed.

Calling this method will typically induce reset if supported by the underlying hardware. It may be called while the device is already open in order to trigger a reset.

Possible error codes:

  • Error::IO_ERROR: An IO error occurred.
  • Error::UNSPECIFIED: An unspecified error occurred. See logs for more details.

Request

NameType

Response

NameType
result Device_Open_Result

Close

Close the Spinel connection.

This method will block until the Device has successfully been put into a closed (preferably low-power) state. An error may be indicated if a problem was encountered that may indicate the device did not close cleanly.

Calling this method will always cause this interface to be closed, even if an error is reported. Thus, the error may be simply ignored or logged.

Calling this method when the device is already closed will do nothing.

Possible error codes:

  • Error::IO_ERROR: An IO error occurred.
  • Error::UNSPECIFIED: An unspecified error occurred. See logs for more details.

Request

NameType

Response

NameType
result Device_Close_Result

GetMaxFrameSize

Fetch the max frame size.

This method may be called at any time. The returned value is an implementation-specific constant.

@return The size of the largest frame that this implementation supports being passed into SendFrame().

Request

NameType

Response

NameType
size uint32

SendFrame

Sends a Spinel-formatted frame to the device.

Calling this method while the device is closed will cause the frame to be dropped and ->OnError() to emit Error::CLOSED.

See ->OnReadyForSendFrames() for flow-control considerations.

Request

NameType
data vector<uint8>[4096]

ReadyToReceiveFrames

Increases the number of additional frames that the caller is currently ready to receive, as a method of inbound flow-control.

The caller can use this method to regulate the speed at which inbound frames are handled. This method should be called periodically to ensure low-latency frame delivery.

Calling this method with a non-zero value indicates to the receiver that the caller is ready to receive the specified additional number of frames.

This method SHOULD NOT be called with a value of zero. If the receiver gets this call with a value of zero, it MUST be ignored.

Frames will not be received until this method is first called with a non-zero value. Once received, the receiver will limit the number of subsequent frames emitted via ->OnReceiveFrame() to the given number of frames.

Calling this method while the device is closed will do nothing.

A reasonable usage pattern would be to first call this method with a value of 4, calling it again with a value of 2 after every second received inbound frame.

Outbound flow control is similarly accomplished via ->OnReadyForSendFrames().

Request

NameType
number_of_frames uint32

OnReadyForSendFrames

Increases the number of additional frames that the Device is currently ready to receive, as a method of outbound flow-control.

The Device uses this callback to regulate the speed at which outbound frames are sent to it. This callback will be called periodically to ensure low-latency frame delivery.

When this callback is invoked with a non-zero value, the device is indicating that it is ready to receive the specified number of additional frames.

This callback SHOULD NOT be invoked with a value of zero, and if a zero value is received via this callback it MUST be ignored.

Frames MUST NOT be sent until this callback is first called with a non-zero value.

A reasonable usage pattern would be for the device to first invoke this callback with a value of 4, invoking it again with a value of 2 after every second received outbound frame.

Inbound flow control is similarly accomplished via ReadyToReceiveFrames().

Response

NameType
number_of_frames uint32

OnReceiveFrame

The callback used to pass incoming Spinel frames to the LoWPAN host stack.

See ReadyToReceiveFrames() for flow-control considerations.

Response

NameType
data vector<uint8>[4096]

OnError

The callback used to indicate that an error has occurred.

If the resulting error caused the device to automatically close, this is indicated via the did_close argument.

Response

NameType
error Error
did_close bool

STRUCTS

DeviceSetup_SetChannel_Response

Defined in fuchsia.lowpan.spinel/spinel.fidl

NameTypeDescriptionDefault

Device_Open_Response

Defined in fuchsia.lowpan.spinel/spinel.fidl

NameTypeDescriptionDefault

Device_Close_Response

Defined in fuchsia.lowpan.spinel/spinel.fidl

NameTypeDescriptionDefault

ENUMS

Error

Type: int32

Defined in fuchsia.lowpan.spinel/spinel.fidl

NameValueDescription
UNSPECIFIED 1

An unspecified error has occurred. This error type should be avoided unless the use of a more specific error would be misleading.

If this error is emitted, it is expected that a more descriptive error will be present in the logs.

Run-time Remediation: Close and re-open the device and attempt to use it. If the error persists, indicate trouble to a higher level and stop.

OUTBOUND_FRAME_TOO_LARGE 2

SendFrame() was called with a frame that was larger than what GetMaxFrameSize() indicated to be the maximum frame size.

Note that MAX_FRAME_SIZE indicates the largest frame size supported by this protocol, whereas GetMaxFrameSize() returns the largest frame size supported by the Device.

This error typically indicates a bug or logic-error in the use of the fuchsia.lowpan.spinel::Device protocol.

This error is only emitted via ->OnError().

INBOUND_FRAME_TOO_LARGE 3

The remote device tried to send us a frame that was too large.

This error typically indicates either frame corruption or a misconfiguration of some sort.

Run-time Remediation: The device should be reset and re-initialized.

This error is only emitted via ->OnError().

INBOUND_FRAME_CORRUPT 4

Garbage-bytes/corruption detected on inbound frame.

This error typically indicates that the connection between the host and the Spinel device is unreliable. This may be caused by hardware problems or implementation bugs.

Run-time Remediation: The device should be reset (by sending a spinel reset frame or by closing and re-opening) and then re-initialized.

This error is only emitted via ->OnError().

IO_ERROR 5

An I/O error has occurred.

When this error is encountered, the device automatically closes.

Run-time Remediation: Re-open the device and attempt to use it. If the error persists, indicate trouble to a higher level (for example, presenting a UI message indicating a malfunction) and stop.

CLOSED 6

This operation cannot be performed while the Spinel device is closed.

This error typically indicates a bug or logic-error in the use of the fuchsia.lowpan.spinel::Device protocol.

This error is only emitted via ->OnError().

UNIONS

DeviceSetup_SetChannel_Result

Defined in fuchsia.lowpan.spinel/spinel.fidl

NameTypeDescription
response DeviceSetup_SetChannel_Response
err zx/status

Device_Open_Result

Defined in fuchsia.lowpan.spinel/spinel.fidl

NameTypeDescription
response Device_Open_Response
err Error

Device_Close_Result

Defined in fuchsia.lowpan.spinel/spinel.fidl

NameTypeDescription
response Device_Close_Response
err Error

CONSTANTS

NameValueTypeDescription
MAX_FRAME_SIZE 4096 uint32