Skip to content

Latest commit

 

History

History
167 lines (145 loc) · 11.5 KB

configuration.md

File metadata and controls

167 lines (145 loc) · 11.5 KB
Raw

Documentation index

Configuration

PJON uses predefined constants, setters and getters to support features and constraints configuration.

Buffers configuration

Before including the library it is possible to define the length of its buffers defining the PJON_MAX_PACKETS and PJON_PACKET_MAX_LENGTH constants:

  #define PJON_MAX_PACKETS 1
  #define PJON_PACKET_MAX_LENGTH 20
  /* PJON can dispatch up to 1 packet with a payload of up to
     20 bytes - packet overhead (5-35 bytes depending on configuration) */

Strategy configuration

Strategies are classes that abstract the physical transmission of data. PJON uses strategies as template parameters although since version 13.0 that complexity is hidden behind a macro:

  #include <PJONSoftwareBitBang.h>
  PJONSoftwareBitBang bus;

In the example above the PJON object is instantiated using the SoftwareBitBang strategy. It is possible to instantiate more than one PJON object using different strategies in the same program:

#include <PJONSoftwareBitBang.h>
#include <PJONEthernetTCP.h>

PJONSoftwareBitBang wiredBus;
PJONEthernetTCP     tcpBus;

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>

Before using ThroughLoRa be sure to have arduino-LoRa library available. Before using ESPNOW be sure to have installed the required tools as described here. Before using MQTTTranslate be sure to have the ReconnectingMqttClient library available.

Random seed

When begin is called an analog pin is used to sample the seed for the random generator. By default PJON uses pin A0 to sample the seed, if you need to use another pin call set_random_seed as shown below:

  bus.set_random_seed(A1); // A1 is used to sample the seed
  bus.begin();             // Seed sampling occurs

Network mode

The network mode can be changed with set_shared_network during runtime, for example moving from local to shared mode:

  bus.set_shared_network(true);

Communication mode

The communication mode can be configured using set_communication_mode passing PJON_SIMPLEX for simplex or mono-directional mode or PJON_HALF_DUPLEX for half-duplex or bidirectional mode:

  // Run in mono-directional PJON_SIMPLEX mode
  bus.set_communication_mode(PJON_SIMPLEX);
  // Run in bi-directional PJON_HALF_DUPLEX mode
  bus.set_communication_mode(PJON_HALF_DUPLEX);

Router mode

When an instance is configured in router mode it is able to receive all incoming packets without any bus or device id filtering. Use set_router to configure the router mode:

  bus.set_router(true);

Sender information

PJON by default includes the sender's information in the packet, If required include_sender_info can be used as shown below to avoid including sender's information:

  bus.include_sender_info(false);

CRC configuration

With set_crc_32 CRC32 can be forced on each packet sent to higher reliability:

  bus.set_crc_32(true);

Packet handling

If manual packet handling is required, packet automatic deletion can be avoided using set_packet_auto_deletion as shown below:

  bus.set_packet_auto_deletion(false);

Acknowledgement

With the acknowledgement enabled the transmitter has reception certainty. It is by default enabled but can be disabled:

  bus.set_acknowledge(false);

Packet identification

The instance can be configured to include a 16 bits packet identifier to guarantee packet uniqueness. Define PJON_INCLUDE_PACKET_ID as described below, if this constant is not present the feature is not included and around 300 bytes of program memory and 80 bytes of RAM are spared:

  // Include the packet id feature
  #define PJON_INCLUDE_PACKET_ID

  // Max number of old packet ids stored to avoid duplication
  // If packet duplication occurs, higher PJON_MAX_RECENT_PACKET_IDS
  #define PJON_MAX_RECENT_PACKET_IDS 10  // By default 10

  #include <PJONSoftwareBitBang.h>

Use set_packet_id to enable the packet identification:

  bus.set_packet_id(true);

See the UsePacketId example to see more in detail how the packet id can be used.

Network service identification

The instance can be configured to include a network service identifier in the packet. Ports from 0 to 8000 are reserved to known network services which index is present in the known network services list, ports from 8001 to 65535 are free for custom use cases. Define PJON_INCLUDE_PORT as described below, if this constant is not present the feature is not used and around 100 bytes of program memory and 2 bytes of RAM are spared:

  // Include the port id feature
  #define PJON_INCLUDE_PORT
  #include <PJONSoftwareBitBang.h>

Use include_port to enable the network service identification:

  bus.include_port(false); // Avoid port inclusion (default)
  bus.include_port(8001);  // Include a port

When a port is configured, packets that contain a different port are discarded. See the PortsUseExample to see more in detail how the port feature can be used.

Hardware identification

The instance can be configured to include the hardware identification. If the feature is used both recipient's and sender's MAC addresses are included in the packet. Define PJON_INCLUDE_MAC as described below, if this constant is not present the feature is not included and around 200 bytes of program memory and 20 bytes of RAM are spared:

  // Include the port id feature
  #define PJON_INCLUDE_MAC
  #include <PJONSoftwareBitBang.h>

  // Device's MAC address
  uint8_t mac[6] = {0, 0, 0, 0, 0, 0};
  PJONSoftwareBitBang bus(mac);

Use include_mac to enable the network service identification by default:

  bus.include_mac(true); // Include MAC address by default

See the BlinkTestMAC example to see more in detail how the MAC feature can be used.