modm API documentation
Sensor Actuator Bus (SAB)

Classes

struct  modm::sab::Action
 Possible Action More...
 
struct  modm::sab::Callable
 Base-class for every object which should be used inside a callback More...
 
class  modm::sab::Interface< Device >
 SAB interface More...
 
class  modm::sab::Master< Interface >
 
class  modm::sab::Response
 Response object for an action call More...
 
class  modm::sab::Slave< Interface >
 SAB Slave More...
 

Macros

#define SAB_ACTION(command, object, function, length)
 Define a sab::Action. More...
 

Enums

enum  modm::sab::Error { modm::sab::ERROR_GENERAL_ERROR = 0x00, modm::sab::ERROR_NO_ACTION = 0x01, modm::sab::ERROR_WRONG_PAYLOAD_LENGTH = 0x02, modm::sab::ERROR_NO_RESPONSE = 0x03 }
 Error code. More...
 
enum  modm::sab::Flags { REQUEST = 0x00, ACK = 0xc0, NACK = 0x80 }
 Flags.
 

Variables

const uint8_t modm::sab::maxPayloadLength = 32
 Maximum length for the payload.
 

Detailed Description

lbuild module: modm:communication:sab

The SAB (**S**ensor **A**ctuator **B**us) is a simple master-slave bus system. It is primarily used to query simple sensors and control actuators inside our robots.

One master can communicate with up to 32 slaves. The slaves are only allowed to transmit after a direct request by the master. They may signal an event by an extra IO line, but this depends on the slave.

Protocol

Features:

Structure

+------+--------+--------+---------+--------------+-----+
| SYNC | LENGTH | HEADER | COMMAND | ... DATA ... | CRC |
+------+--------+--------+---------+--------------+-----+

Header

7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
| Flags | ADDRESS |
+---+---+---+---+---+---+---+---+
Flags | Meaning
--------+---------
0 0 | request by the master
0 1 | reserved
1 0 | negative response from the slave (NACK)
1 1 | positive response from the slave (ACK)

The second bit is always false when the master is transmitting. In the other direction, when the slaves are responding, the second bit has to following meaning:

Electrical characteristics

Between different boards CAN transceivers are used. Compared to RS485 the CAN transceivers have the advantage to work without a separate direction input. You can just connected the transceiver directly to the UART of your microcontroller.

Within a single PCB, standard digital levels are used (either 0-3,3V or 0-5V) in a multi-drop configuration. Meaning it does not allow multiple drivers but multiple receivers. The idle state of a UART transmission line is high, so standard TTL-AND gates have to be used for bundling transmission lines from multiple slaves.

Both approaches can be combined to reduce the number of needed CAN transceivers on a single board. Between two boards you should always use transceivers and therefore differential signaling to improve noise immunity.

The signal lines to indicate events by the slave are strict optional, you may or may not use them (if the slave provides them).

Macro Definition Documentation

#define SAB_ACTION

Define a sab::Action.

Example:

class Sensor : public modm::sab::Callable
{
public:
void
sendValue(modm::sab::Response& response)
{
response.send(this->value);
}
void
doSomething(modm::sab::Response& response, const uint32_t* parameter)
{
// ... do something useful ...
response.send();
}
// ...
private:
int8_t value;
};
Sensor sensor;
{
SAB_ACTION(0x57, sensor, Sensor::sendValue, 0),
SAB_ACTION(0x03, sensor, Sensor::doSomething, sizeof(uint32_t)),
};

A complete example is available in the example/sab folder.

Parameters
commandCommand byte
object
functionMember function of object
lengthParameter size in bytes
See also
modm::sab::Action

Enumeration Type Documentation

Error code.

Error codes below 0x20 are reserved for the system. Every other code may be used by user.

Enum ValuesDocumentation
ERROR_GENERAL_ERROR 

Universal error code.

Use this code if you're not sure what error to signal. If the user should react to the error code, create a specific one for the given problem.

ERROR_NO_ACTION 

No corresponding action found for this command.

ERROR_WRONG_PAYLOAD_LENGTH 

Unexpected payload length.

The payload length of the received message differs from the expected length for the given command.

ERROR_NO_RESPONSE 

No response given by the user.

This error code is generated when no response method is called by the user during an action callback.