What is a Strategy

A strategy is an abstraction layer used to physically transmit data. Thanks to the strategies PJON can operate transparently on a wide range of media and protocols. Take a look at the strategies video introduction for a brief showcase of their features.

The table below lists the strategies available:

Strategy Physical layer Protocol Inclusion
AnalogSampling Light PJDLS #include <PJONAnalogSampling.h>
Any Virtual inheritance Any #include <PJONAny.h>
DualUDP Ethernet/WiFi UDP #include <PJONDualUDP.h>
ESPNOW WiFi ESPNOW #include <PJONESPNOW.h>
EthernetTCP Ethernet/WiFi TCP #include <PJONEthernetTCP.h>
GlobalUDP Ethernet/WiFi UDP #include <PJONGlobalUDP.h>
LocalFile File system None #include <PJONLocalFile.h>
LocalUDP Ethernet/WiFi UDP #include <PJONLocalUDP.h>
MQTTTranslate Ethernet/WiFi MQTT #include <PJONMQTTTranslate.h>
OverSampling Radio PJDLR #include <PJONOverSampling.h>
SoftwareBitBang Wire PJDL #include <PJONSoftwareBitBang.h>
ThroughLoRa Radio LoRa #include <PJONThroughLora.h>
ThroughSerial Wire TSDL #include <PJONThroughSerial.h>

How the strategy is implemented

A Strategy is a class containing a set of methods used to physically send and receive data along with the required getters to handle retransmission and collision:

bool begin(uint8_t did = 0)

Receives an optional parameter of type uint8_t (when PJON calls begin it passes its own device id); returns true if the strategy is correctly initialized. There is no doubt that the strategy should not know about the PJON's device id, although that is practically useful in many cases.

uint32_t back_off(uint8_t attempts)

receives a paramenter of type uint8_t and returns the suggested delay for a given number of attempts.

bool can_start()

Returns true if the medium is free for use and false if the medium is busy.

void handle_collision()

Handles a collision.

uint8_t get_max_attempts()

Returns the maximum number of attempts in case of failed transmission.

uint16_t get_receive_time()

Returns the minimum polling time required to successfully receive a frame.

void send_frame(uint8_t *data, uint16_t length)

Receives a pointer to the data and its length and sends it through the medium. The sending procedure must be blocking.

uint16_t receive_frame(uint8_t *data, uint16_t max_length) { ... };

Receives a pointer where to store received information and an unsigned integer signalling the maximum data length. It should return the number of bytes received or PJON_FAIL.

void send_response(uint8_t response)

Send a response to the packet's transmitter.

uint16_t receive_response()

Receives a response from the packet's receiver.

// Simple Serial data link layer implementation example
void send_response(uint8_t response) {
  Serial.print(response);
};

Above it is demonstrated how simply other communication protocols can be used to define a new custom strategy.

How to implement a custom strategy

To define a new custom strategy you need to create a new folder named for example YourStrategyName in the src/strategies directory and create the necessary file YourStrategyName.h:

class YourStrategyName {
  public:
    uint32_t back_off(uint8_t attempts) { };
    bool     begin(uint8_t did) { };
    bool     can_start() { };
    uint8_t  get_max_attempts() { };
    uint16_t get_receive_time() { };
    uint16_t receive_frame(uint8_t *data, uint16_t max_length) { };
    uint16_t receive_response() { };
    void     send_response(uint8_t response) { };
    void     send_frame(uint8_t *data, uint16_t length) { };
};

If all is correct it should be possible to instantiate PJON using the new strategy:

PJON<YourStrategyName> bus(44);
// Use PJON as always

Strategy related methods required for configuration can be defined within the strategy. For example the SoftwareBitBang strategy uses a dedicated setter for the communication pin:

bus.strategy.set_pin(12);

This document is automatically generated from the github repository. If you have noticed an error or an inconsistency, please report it opening an issue here
Updated on 06 November 2020 at 17:55:28

Strategies abstraction

PJON uses strategies to physically transmit data, abstracting the data link from its procedure. A Strategy is a class containing the minimum required set of features to support transmision and reception of frames; many strategies are available to communicate data through various media and protocols. Take a look at the strategies video introduction for a brief showcase of their features.

STRATEGIES

The PJON software big box

The PJON 13.0 big box is a limited edition. It contains the PJON protocol handbook, the PJON protocol source code in CD and the stickers. This product contains everything you need to master the PJON protocol and its implementation, although it is also designed to nicely fit in your big box collection. Choosing this handy kit, you will always have PJON with you in different formats, also when not being connected to Internet. Buying PJON products you support its further development and enhancement.


BUY NOW!