Differentially Operated Serial Ethernet

Driver for connecting RIOT devices using a single bus wire. More...

Detailed Description

Driver for connecting RIOT devices using a single bus wire.

About

This driver enables RIOT nodes to communicate by Ethernet over a serial bus. This enables them to interact in an easy and cheap manner using a single bus wire with very low hardware requirements: The used microcontrollers just need to feature at least one UART and one optional GPIO that is able to raise interrupts.

Wiring

DOSE wiring

For bus access, you need a CAN transceiver, since the DOSE uses the PHY layer of CAN for the electrical connection of the nodes. Every transceiver IC operating with the right voltage levels should do. (If you are on a 3.3V MCU, you could use an IC such as the SN65HVD233.)

Basically, UART TX and RX are connected to respective pins of the transceiver. In addition, the RX pin can also be connected to the sense GPIO. In this case, the bus allocation can be detected more precisely and collisions are less likely.

How it works

Some technical details for those interested: The Ethernet frames are sent onto the bus using uart_write() while observing the received echo from the bus. This way collisions are detected (received echo != transmitted octet) and retransmissions are scheduled. The frames are appended with a CRC16 to protect the system from transmission errors.

Modules
	Differentially Operated Serial Ethernet (DOSE) driver compile configuration

Files
file	dose_params.h
	Default configuration for the Differentially Operated Serial Ethernet driver.
file	dose.h
	Driver for the Differentially Operated Serial Ethernet module.

Data Structures
struct	dose_t
	DOSE netdev device. More...
struct	dose_params_t
	Struct containing the required configuration. More...

Macros
#define	DOSE_FRAME_CRC_LEN   (2)
	CRC16 is used.
#define	DOSE_FRAME_LEN   (ETHERNET_FRAME_LEN + DOSE_FRAME_CRC_LEN)
	dose frame length

Functions
void	dose_setup (dose_t *dev, const dose_params_t *params, uint8_t index)
	Setup a DOSE based device state. More...

Escape octet definitions
#define	DOSE_OCTET_END   (0xFF)
	Magic octet indicating the end of frame.
#define	DOSE_OCTET_ESC   (0xFE)
	Magic octet escaping 0xFF in byte stream.

State definitions
The drivers internal state that is hold in dose_t.state
enum	dose_state_t {   DOSE_STATE_INIT = 0x00, DOSE_STATE_BLOCKED = 0x01, DOSE_STATE_IDLE = 0x02, DOSE_STATE_RECV = 0x03,   DOSE_STATE_SEND = 0x04, DOSE_STATE_ANY = 0x0F }

Signal definitions
A signal controls the state machine and may cause a state transition
enum	dose_signal_t {   DOSE_SIGNAL_NONE = 0x00, DOSE_SIGNAL_INIT = 0x10, DOSE_SIGNAL_GPIO = 0x20, DOSE_SIGNAL_UART = 0x30,   DOSE_SIGNAL_XTIMER = 0x40, DOSE_SIGNAL_SEND = 0x50, DOSE_SIGNAL_END = 0x60 }

Flag definitions
Hold in dose_t.flags
#define	DOSE_FLAG_RECV_BUF_DIRTY   (BIT0)
	Receive buffer contains a complete unhandled frame.
#define	DOSE_FLAG_END_RECEIVED   (BIT1)
	END octet has been received.
#define	DOSE_FLAG_ESC_RECEIVED   (BIT2)
	ESC octet has been received.

Opt definitions
Hold in dose_t.opts
#define	DOSE_OPT_PROMISCUOUS   (BIT0)
	Don't check the destination MAC - pass every frame to upper layers.

Enumeration Type Documentation

dose_signal_t

enum dose_signal_t

Enumerator
DOSE_SIGNAL_NONE	No signal ...
DOSE_SIGNAL_INIT	Init the state machine.
DOSE_SIGNAL_GPIO	Sense GPIO detected a falling edge.
DOSE_SIGNAL_UART	Octet has been received.
DOSE_SIGNAL_XTIMER	Timer timed out.
DOSE_SIGNAL_SEND	Enter send state.
DOSE_SIGNAL_END	Leave send state.

Definition at line 97 of file dose.h.

dose_state_t

enum dose_state_t

Enumerator
DOSE_STATE_INIT	Initial state that will never be reentered.
DOSE_STATE_BLOCKED	The driver just listens to incoming frames and blocks outgress frames.
DOSE_STATE_IDLE	Frames will be received or sent.
DOSE_STATE_RECV	Currently receiving a frame.
DOSE_STATE_SEND	Currently sending a frame.
DOSE_STATE_ANY	Special state filter used internally to observe any state transition.

Definition at line 83 of file dose.h.

Function Documentation

dose_setup()

void dose_setup	(	dose_t *	dev,
		const dose_params_t *	params,
		uint8_t	index
	)

Setup a DOSE based device state.

Parameters

[out]	dev	Handle of the device to initialize
[in]	params	Parameters for device initialization
[in]	index	Index of params in a global parameter struct array. If initialized manually, pass a unique identifier instead.