Api

In this page you will find about the functions you must implement and the objects you may use on your sketches.

Functions

presentation

void presentation()

This function must be implemented (at least present) in your sketch. It will be called at the start of your node and every time your nome receive an I_PRESENTATION.

@params: None

@return: None

receive

void receive(const MyMessage &msg)

If you want to handle messages you must implement this function on your sketch. If you don’t implement it, you won’t be able to handle the messages and they will just be ignored, if they are not “special” messages which are handled behind the scenes.

Then, you will use the MyMessage object to see what is inside the message.

@params:

  • msg: It takes a reference of a MyMessage that you will to manipulate.

@return: None

receiveTime

void receiveTime(unsigned long time)

This function will be called every time your node receives time from controller. So if you want to handle it, you must implement this functions.

@params:

  • time:

@return: None

getConfig

ControllerConfig getConfig()

It takes the most recent node configuration received from controller

@params: None

@return: ControllerConfig struct with all configuration

getNodeId

uint8_t getNodeId()

@params: None

@return: Node’s id

loadState

uint8_t loadState(uint8_t pos)

Load a state (from local EEPROM).

@params:

  • pos: The position to fetch value from 0 to 255

@return: Value that was stored in position

present

void present(uint8_t sensorId, uint8_t sensorType, const char* description="", bool ack=false)

Each node must present all attached sensors before any values can be handled correctly by the controller. It is usually good to present all attached sensors after power-up in setup().

@params:

  • sensorId: Select a unique sensor id for this sensor. Choose a number between 0-254.
  • sensorType: The sensor type. See sensor typedef in MyMessage.h.
  • description: A textual description of the sensor.
  • ack: Set this to true if you want destination node to send ack back to this node. Default is not to request any ack.
  • description: A textual description of the sensor.

@return: None

request

void request(uint8_t childSensorId, uint8_t variableType, uint8_t destination=GATEWAY_ADDRESS)

It sends an requesting package.

@params:

  • childSensorId: The variable’s node’s id you want to request.
  • variableType: The type of variable you are requesting.
  • destination: Destination node. The default destination is the Gateway.

@return: None

requestTime

void requestTime()

Requests time from controller. Answer will be delivered to receiveTime function in sketch.

@params: None

@return: None

saveState

void saveState(uint8_t pos, uint8_t value)

Save a state (in local EEPROM). Good for actuators to “remember” state between power cycles. You have 256 bytes to play with. Note that there is a limitation on the number of writes the EEPROM can handle (~100 000 cycles on ATMega328).

@params:

  • pos: The position to store value in 0 to 255
  • value: Value to store in position

@return: None

send

bool send(MyMessage &msg, bool ack=false)

Sends a message to gateway or one of the other nodes in the radio network

@params:

  • msg: It takes a reference to a Message object to send.
  • ack: Set this to true if you want destination node to send ack back to this node. Default is not to request any ack.

@return: Returns true if message reached the first stop on its way to destination.

sendBatteryLevel

void sendBatteryLevel(uint8_t level, bool ack=false)

Send this nodes battery level to gateway.

@params:

  • level: Level between 0-100(%)
  • ack: Set this to true if you want destination node to send ack back to this node. Default is not to request any ack.

@return: None

sendHeartbeat

void sendHeartbeat()

Send a heartbeat message (I’m alive!) to the gateway/controller. The payload will be an incremental 16 bit integer value starting at 1 when sensor is powered on.

Allows node to send heartbeat and controller to ping nodes.

@params: None

@return: None

sendSketchInfo

void sendSketchInfo(const char* name, const char* version, bool ack=false)

It sends sketch meta information to the gateway. Not mandatory but a nice thing to do.

@params:

  • name String containing a short Sketch name or NULL if not applicable
  • version String containing a short Sketch version or NULL if not applicable
  • ack Set this to true if you want destination node to send ack back to this node. Default is not to request any ack.

@return: None

sleep

void sleep(unsigned long ms)

Sleep (PowerDownMode) the MCU and radio. Wake up on timer.

@params:

  • ms: Number of milliseconds to sleep.

@return: None

smartSleep

void smartSleep(unsigned long ms)

@params:

  • ms: Number of milliseconds to sleep.

sleep

bool sleep(uint8_t interrupt, uint8_t mode, unsigned long ms=0)

Sleep (PowerDownMode) the MCU and radio. Wake up on timer or pin change. See: http://arduino.cc/en/Reference/attachInterrupt for details on modes and which pin is assigned to what interrupt. On Nano/Pro Mini: 0=Pin2, 1=Pin3

@params:

  • interrupt: Pin that should trigger the wakeup
  • mode: RISING, FALLING, CHANGE
  • ms: Number of milliseconds to sleep or 0 to sleep forever

@return: True if wake up was triggered by pin change and false means timer woke it up.

smartSleep

bool smartSleep(uint8_t interrupt, uint8_t mode, unsigned long ms=0)

@params:

  • interrupt: Pin that should trigger the wakeup
  • mode: RISING, FALLING, CHANGE
  • ms: Number of milliseconds to sleep or 0 to sleep forever

@return: True if wake up was triggered by pin change and false means timer woke it up.

sleep

int8_t sleep(uint8_t interrupt1, uint8_t mode1, uint8_t interrupt2, uint8_t mode2, unsigned long ms=0)

Sleep (PowerDownMode) the MCU and radio. Wake up on timer or pin change for two separate interrupts. See: http://arduino.cc/en/Reference/attachInterrupt for details on modes and which pin is assigned to what interrupt. On Nano/Pro Mini: 0=Pin2, 1=Pin3

@params:

  • interrupt1 First interrupt that should trigger the wakeup
  • mode1 Mode for first interrupt (RISING, FALLING, CHANGE)
  • interrupt2 Second interrupt that should trigger the wakeup
  • mode2 Mode for second interrupt (RISING, FALLING, CHANGE)
  • ms Number of milliseconds to sleep or 0 to sleep forever

@return: Pin number wake up was triggered by pin change and negative if timer woke it up.

smartSleep

int8_t smartSleep(uint8_t interrupt1, uint8_t mode1, uint8_t interrupt2, uint8_t mode2, unsigned long ms=0)

@params:

  • interrupt1 First interrupt that should trigger the wakeup
  • mode1 Mode for first interrupt (RISING, FALLING, CHANGE)
  • interrupt2 Second interrupt that should trigger the wakeup
  • mode2 Mode for second interrupt (RISING, FALLING, CHANGE)
  • ms Number of milliseconds to sleep or 0 to sleep forever

@return: Pin number wake up was triggered by pin change and negative if timer woke it up.

wait

void wait(unsigned long ms)

Wait for a specified amount of time to pass. Keeps process()ing. This does not power-down the radio nor the Arduino. Because this calls process() in a loop, it is a good way to wait in your loop() on a repeater node or sensor that listens to messages.

@params:

  • ms: Number of milliseconds to sleep.

@return: None

Objects

MyMessage

MyMessage msg1(CHILD_ID, CHILD_TYPE); MyMessage msg2();

This object will handle incoming and outcoming messages. You must create one message for each sensor you have in your node.

Attributes

uint8_t last

8 bit - Id of last node this message passed

uint8_t sender

8 bit - Id of sender node (origin)

uint8_t destination

8 bit - Id of destination node

uint8_t version_length

2 bit - Protocol version

1 bit - Signed flag

5 bit - Length of payload

uint8_t command_ack_payload

3 bit - Command type

1 bit - Request an ack - Indicator that receiver should send an ack back.

1 bit - Is ack messsage - Indicator that this is the actual ack message.

3 bit - Payload data type

uint8_t type

8 bit - Type varies depending on command

uint8_t sensor

8 bit - Id of sensor that this message concerns.

char data[MAX_PAYLOAD + 1];

That is the message’s payload

Methods

getCommand

uint8_t getCommand()

@params: None

@return: It returns the value of command (type of message). E.g.: C_SET, C_REQ, ...

isAck

bool isAck()

@params: None

@return: It return if it is an ack or not.

set

MyMessage& set(void* payload, uint8_t length)

MyMessage& set(const char* value)

MyMessage& set(float value, uint8_t decimals)

MyMessage& set(uint8_t value)

MyMessage& set(uint32_t value)

MyMessage& set(int32_t value)

MyMessage& set(uint16_t value)

MyMessage& set(int16_t value)

This function set the message’s payload. There are a lot of overwritten in this function, which allow you to send many types of value.

@params:

  • payload:
  • length:
  • value:
  • decimals:

@return: It returns a reference to your MyMessage object.

setDestination

MyMessage& setDestination(uint8_t destination)

It sets the destination of the package.

@params:

  • destination

@return: It returns a reference to your MyMessage object.

setSensor

MyMessage& setSensor(uint8_t sensor)

It sets the sensor’s id which will be send on the protocol header.

@params:

  • sensor

@return: It returns a reference to your MyMessage object.

setType

MyMessage& setType(uint8_t type)

It sets the sensor’s type which will be send on the protocol header.

@params:

  • type

@return: It returns a reference to your MyMessage object.