stackDistSync.c File Reference

this is the stack file for particles based on the chipcon cc1010 all-in-one mobile chip. More...

#include <chipcon/reg1010.h>
#include <chipcon/partCboard.h>
#include <chipcon/hal.h>
#include <chipcon/sdccutils.h>
#include "acltypes.h"
#include <chipcon/partCStack.h>

Go to the source code of this file.

Debug switches

#define DEBUG_USE_UART

this switch activates debug messages that are sent through a serial port

#define DEBUG_USE_UART1_FOR_DUMPING

if defined, this switch activates output through uart1, otherwise output is directed to uart0 (default).

#define DEBUG_VERIFY_SCRAMBLING

this switch turns on scrambling and tests the fitness of the scrambling macros

RF defines and variables

#define RF_STATE_MASTER   BIN(00000001)

this bit is not used in distributed sync mode

#define RF_STATE_ALONE   BIN(00000010)

rf status bit: if a master didn't here anything from another node for a certain number of times (normally some minutes) it sets this bit, and resets it at the first reception of a packet.

#define RF_STATE_IN_SYNC   BIN(00000100)

rf status bit: the last synchronization was successful.

#define RF_STATE_TRAFFIC_GROUP   BIN(00001000)

rf status bit: if this bit is 0, the the stack is within an idle group (it may not send and it does not have to recieve packets).

#define RF_STATE_LONG_SEARCH_FOR_BEACON   BIN(00010000)

rf status bit: the node is trying to become master.

#define RF_STATE_SHORT_SEARCH_FOR_BEACON   BIN(00100000)

rf status bit: a master node goes into this mode every time after sending the 100th beacon.

#define RF_STATE_RUNNING   BIN(10000000)

rf status bit: rf layer is running

#define RF_SYNC_MAX_SLOT_COUNT   15

every RF_SYNC_MAX_SLOT_COUNT slots, a master sends a sync signal / a slave tries to receive a sync signal.

#define RF_USE_ALONE_DETECTION

if this switch is defined, the stack tries to detect the situation that a node is not connected to a network and use this information for saving energy.

#define RF_ALONE_TEST_FAILED_THRESHOLD   167

how many slots without reception of a beacon must appear, before a node thinks it is alone.

#define RF_ALONE_DEEP_SLEEP

this switch controls the actions taken if the node detects that it is alone.

#define RF_PREAMBLE_LENGTH_TX   20

the number of preamble bytes that are sent before any RF packet on send

#define RF_PREAMBLE_LENGTH_RX   20

the number of preamble bytes need to be detected before any RF packen on receive

#define RF_MAX_SYNC_JITTER   4000ul

the maximum time (im us) that a slave is waiting in a sync slot for the master sync signal.

#define RF_SLOT_LENGTH_IN_US   36865ul

the slot length im us - according to the manual.

#define RF_BEACON_SEARCH_SLOTS_STARTUP   50

number of slots to search for am master at startup.

#define RF_MASTER_SEARCH_SLOTS_AFTER_ALONE   167

number of slots to when waking up from alone low power sleep

#define RF_MAX_FAILED_SYNC_COUNT   10

after not being able to receive a sync signal for RF_MAX_FAILED_SYNC_COUNT times, a slave goes into status RF_STATE_SYNC_MASTER_LONG_TEST

#define RF_SYNC_ADDITIONAL_OFFSET   0xA3BD

additional offset added to start offset transmitted in beacon in us without this, the slave would wake up slightly to early.

#define RF_ARBITRATION_RSSI_THRESHOLD   0x78

maximum rssi signal strength that may be read during arbitration to be able to send a packet.

#define RF_ALONE_TEST_RSSI_THRESHOLD   0xC0

the rssi threshold used for the alone test and traffic indication.

#define RF_RENDEZVOUS_PACKET_START_HI   0x96

value of timer register TH0 when data or beacon send/receive should begin.

#define RF_RENDEZVOUS_ARBITRATION_START_HI   0x72

value of timer register TH0 when arbitration should begin.

#define RF_ARBITRATION_TIMER_TICS_OTHER_PERIODS   0x390

how many timer0 tics between rendezvous points optimal value for 76.8 kBaud Manchester: 0x1EA for 2 samples / 13 bit sent 0x24C for 3 samples / 20 bit sent optimal value for 76.8 kBaud NRZ: 0x3D8 for 3 samples / 20 bit sent (for testing and rssi dumping use 0x500) 0x358 - 0x380

#define RF_BUFFER_SIZE   64

size of the sending and reception buffer

#define RF_RENDEZVOUS_TRAFFIC_INDICATION_HI   0xAE

value of timer register TH0 when traffic indication signal should be sent.

#define RF_RENDEZVOUS_ALONE_TEST_HI   0xAA

value of timer register TH0 when traffic indication signal should be sent.

data volatile byte rfState = 0

byte that holds the current rf state.

data byte rfScramblerReg = BIN(01101100)

current value of the scrambler register which is used to generate a dc-free code with limited run-length for rf transmission.

data unsigned long randomNumberReg

random number generator register

data unsigned short tEndAvg = 0

the average timer value on the master after sending the beacon.

xdata TIMER_DATA periodDataSlot

the calculated periods for the timer registers

xdata signed short moduloTimer0

the modulo word for timer adjustment of timer 0

xdata byte rssiSamples [16]

the rssi samples acquired during arbitration

unsigned short arbitrationGood = 0

statistic counter: number of times arbitration succeeded (media access granted)

unsigned short arbitrationBad = 0

statistic counter: number of times arbitration failed (media access denied)

RF_RXTXPAIR_SETTINGS code RF_SETTINGS

xdata RF_RXTXPAIR_CALDATA RF_CALDATA

Calibration data.

xdata byte rfFieldStrength

holds the value of the currently used field strength.

xdata unsigned short rfMaxTimerValue

this is a scratch variable that may hold the maximum timer value of timer 0 if timer0 is measured on a certain place in the program.

LL defines and variables

#define LL_PROTOCOL_VERSION   4

the protocol version

#define LL_CRC16_POLY   0x1021

check polynom for crc 16

#define LL_CRC16_INIT   0xFFFF

initial value of the crc16 register

#define LL_CRC_OK   0

modulo for correct crc reception (zero)

#define LL_STATE_SEND_SUCCESS   BIN(00000001)

true if the last packet was sent successfully, false otherwise. updated when LL_STATE_NEED_TO_SEND is reset.

#define LL_STATE_CTRL_MESSAGE_INSERTED   BIN(00000010)

true if packet in send buffer has been replaced by a control message

#define LL_STATE_NEED_TO_SEND   BIN(00000100)

ll status bit: if 1, the data in the send buffer has to be sent.

#define LL_STATE_RECEIVE_BUFFER_LOCKED   BIN(00001000)

true if receive buffer is locked, false otherwise

#define LL_STATE_NEW_DATA   BIN(00010000)

true if new data has arrived in the receive buffer after the last time this flag was set to 0, false otherwise

#define LL_STATE_PACKET_JUST_SENT   BIN(00100000)

true if a packet was sent in the current slot, false otherwise

#define LL_STATE_PACKET_JUST_RECEIVED   BIN(01000000)

true if a packet was received in the current slot, false otherwise

#define LL_STATE_RUNNING   BIN(10000000)

true if ll layer is running, false otherwise

xdata byte LL_sequence_no

current LL sequence number

data volatile byte llState = 0

byte that holds the current rf state.

ACL defines and variables

#define ACL_SUBSCRIPTIONLIST_LENGTH   8

length of the subscription list, must be dividable by 4

#define ACL_CONTROL_MESSAGES_TIMEOUT   30

timeout in slots for control messages

#define ACL_TYPE_ACM_H   ACL_TYPE_ACM_HI

synonym

#define ACL_TYPE_ACM_L   ACL_TYPE_ACM_LO

synonym

Helper functions

void DebugDumpRfState ()

sends a nice representation of the the current rf status to uart

void DebugDumpReceivedAclPacket ()

dumps a representation of the last received packet payload (stored in LL_payload_received) to the serial port.

void putchar (char c)

classic putchar function that is used to output a character to the "screen", in our case the serial port.

void DebugBuildTestPacketACL ()

builds a test packet.

"PIC" Layer

actually CC1010 layer - board setup.
sets up the board: LEDs, watchdog timer, memory access, serial port

void ParticleInit ()

sets up the board: LEDs, watchdog timer, memory access, serial port

byte AppSelfTest (char *result)

RF Layer Functions

void RFInit ()

calibrates the transceiver. calculates timer periods needed for rf.

void RFStart ()

starts the timer. this turns on receiving, sending and sync. turns on rssi.

void RFStop ()

stops the timer.

void RFSetModeTransmit ()

faster version of the halRFSetRxTxOff function to start sending.

void RFSetModeReceive ()

faster version of the halRFSetRxTxOff function to start receiving prior execution of halRFSetRxTxOff() is required.

void RFInitRandom ()

gets a true random number for initialization of the random number generator

unsigned short RFReceivePacket (xdata TIMER_DATA *timeOutPeriodData, bool waitForPacketsRendevouz, bool ignoreDataPackets)

the general function to receive a packet.

byte RFArbitrationBit (bool sendOrListen, byte syncTimeH, byte syncTimeL)

does the arbitration for one arbitration slice.

byte RFArbitrationBitDebug (bool sendOrListen, byte syncTimeH, byte syncTimeL)

does the arbitration for one arbitration slice.

bool RFArbitration (bool tryToObtainMediaAccess, bool syncPrio)

tries to get media access through the can arbitration process.

bool RFAloneTest (bool send)

this method is to be called in a sync slot immediately after sending/receiving of the sync packet has occurred.

byte RFAloneRandomNumberOfSeconds ()

returns the number of seconds that the node should stay in deep sleep when it detects that it is alone.

unsigned short RFAloneRandomNumberOfSlots ()

returns the number of slots that the node should stay alone mode (suppressing communication) when it detects that it is alone.

void RFLowPowerSleep (byte sleepTime)

sends the node into power-saving mode for 10-26 seconds. this is done by turning on the 32KHz clock, switching off the 14MHz clock and switching the core to the low frequency clock. the node stays in low freq mode for a given number of seconds and then switches back to high freq mode and returns from the function.

bool RFShallISendSync (byte slotCount)

returns true with the following probabilities, depending on the given slot number.

byte RFScramble (byte b)

this function wraps the marcro RF_SCRAMBLE.

byte RFDescramble (byte b)

this function wraps the marcro RF_SCRAMBLE.

bool RFSendPacket (bool sync)

sends length chars of the packetContent string in an rf packet.

bool RFLongSearchForBeacon (unsigned short numTries)

does a long search for a beacon.

bool RFShortSearchForBeacon ()

does a short search for beacon.

LL Layer Functions

byte LLGetIDFromHardware ()

reads particle address from flash

void LLInit ()

initializes the ll layer (and the lower layers)

void LLStart ()

starts the ll layer and the rf layer

void LLStop ()

stops the ll layer and the rf layer

void LLSlotEnd ()

i guess this function is called at the end of the ISR before returning to "application level".

void LLAbortSending ()

unqueues the current packet.

void LLSetSendingSuccess ()

sets the rfState and llState bits to their sending success value

byte LLSendingBusy ()

byte LLGetSendSuccess ()

byte LLIsActive ()

void LLSetDataToOld ()

resets the "new data flag".

void LLLockReceiveBuffer ()

locks the receive buffer, i.e.

byte LLReceiveBufferLocked ()

void LLReleaseReceiveBuffer ()

unlocks the receive buffer, i.e.

void LLSetDataToNew ()

sets the "new data flag".

byte LLDataIsNew ()

byte LLGetFieldStrength ()

void LLSetFieldStrength (byte value)

sets the field strength at which packets are sent out (0-255)

unsigned short LLCalcCRC16 (byte *header_data, byte *payload_data, byte payload_size)

calculates the crc-16 checksum over the rf packet (ll header + payload)

byte LLSendPacket (byte slot_limit)

prepares the LL header and instructs the rf layer to send the packet out (via flag).

byte LLGetRemainingPayloadSpace ()

byte LLSentPacketInThisSlot ()

ACL Layer Functions

void ACLStartUp ()

is the first function in any case, runs selftest and aclinit

void ACLInit ()

start ACL and lower layers, resets the whole stack

byte ACLSubscribe (byte LL_type_h, byte LL_type_l)

adds a type to the subscription list

byte ACLUnsubscribe (byte LL_type_h, byte LL_type_l)

deletes a type out of the subscription list

void ACLFlushSubscriptions ()

deletes all subscriptions (not the default ones)

void ACLSubscribeAll ()

subscribes to any possible type (all packets are received)

void ACLAnswerOnACM ()

if a control msg comes in that requires an answer, it is answered

void ACLNoAnswerOnACM ()

if a control msgs comes in that requires an answer, it will not be answered

byte ACLSubscribeDefault ()

subscribes to the default types (control msgs..)

byte ACLVerifySubscription (byte type_h, byte type_l)

checks if a subscription is there

byte ACLProcessControlMessages ()

internal: is called if control msg is there

void ACLSetFieldStrength (byte power)

sets the field strength of transmitter signals

byte ACLSendingBusy ()

returns true if LL has Packet in send queue

byte ACLGetSendSuccess ()

returns the result of last packet transmission.

byte ACLMatchesMyIP (char *buffer, byte start)

checks, if buffer holds my IP

byte ACLSendPacket (byte slot_timeout)

queues a packet for transmission

void ACLAbortSending ()

stops a running transmission

byte ACLClearSendData ()

deletes the send buffer of ACL

bool ACLAddNewType (byte type_h, byte type_l)

adds a new type tuple to the payload

byte ACLAddData (byte newByte)

adds one byte data into the ACL send buffer

byte ACLGetRemainingPayloadSpace ()

returns the number of free bytes in the transmit buffer

byte ACLGetReceivedPayloadLength ()

returns the number of payload bytes of the last packet received

signed char ACLGetReceivedDataLength (byte type_h, byte type_l)

searches the last received packet for the given type and returns the data length of the entry found.

char * ACLGetReceivedData (byte type_h, byte type_l)

char ACLGetReceivedByte (byte type_h, byte type_l, byte position)

searches the first occurrence of type tuple and returns the position-th byte after that tuple

byte ACLFoundReceivedType (byte type_h, byte type_l)

void ACLSetControlMessagesBehaviour (boolean ignore, boolean pass)

note that the settings are independent.

byte ACLSentPacketInThisSlot ()

void ACLStart ()

restart ACL after ACLstop()

void ACLStop ()

stops the RF stack. Everything is hold, continues after ACLstart. msg stay in queue.

void ACLLockReceiveBuffer ()

locks the receive buffer: no new msgs are received

byte ACLReceiveBufferLocked ()

void ACLReleaseReceiveBuffer ()

un-lock the receivebuffer;

void ACLSetDataToOld ()

set received data to "old": means ACLDataIsNew will not return true unless a new packet was received

void ACLSetDataToNew ()

set received data to "new": means ACLDataIsNew will return true until ACLSetDataToOld() is called

byte ACLDataIsNew ()

byte ACLDataReceivedInThisSlot ()

byte ACLDataIsNewNow ()

synonym for ACLDataReceivedInThisSlot()

byte ACLAdressedDataIsNew ()

byte ACLAdressedDataIsNewNow ()

byte ACLSendPacketAdressed (nodeAddrType *address, byte timeout)

sends out the current packet with a target ID

Received Packet Variables

An received data packet is copied into these variables once it arrived completely and and succeeded the crc test

xdata byte LL_header_received [LL_HEADER_SIZE]

last header received

xdata byte LL_payload_received [LL_PAYLOAD_SIZE]

last payload received

xdata byte LL_payload_received_length

length of last payload received

xdata byte LL_tail_received [LL_TAIL_SIZE]

last tail received

Packet Receive Buffer

During reception, an incoming packet is written to these variables and on complete arrival and successful crc test (if it is a data packet) is copied into the Received Packet variables.
By this, the next packet can be received immediately.

volatile xdata byte LL_header_receivebuffer [LL_HEADER_SIZE]

temp store: header received

volatile xdata byte LL_payload_receivebuffer [LL_PAYLOAD_SIZE]

temp store: payload received

volatile xdata byte LL_payload_receivebuffer_length

temp store: of last payload received

volatile xdata byte LL_tail_receivebuffer [LL_TAIL_SIZE]

temp store: tail received

Variables For Next Packet to Send

The user and the ACL function write the payload of the next packet to send into these variables.
No header and tail variables are needed for "send" because they are evaluated not until sending time.

xdata byte LL_payload_send [LL_PAYLOAD_SIZE]

next payload to send

xdata byte LL_payload_send_length

length of next payload to send

Packet To Send Buffer

On calling LLSendPacket(), the payload to send is copied into these send buffer variables.
The LL_payload_send variable can be accessed again immediately. The "realtime" part only accesses these variables.

xdata byte LL_header_sendbuffer [LL_HEADER_SIZE]

temp store: header to send

xdata byte LL_payload_sendbuffer [LL_PAYLOAD_SIZE]

temp store: payload to send

xdata byte LL_payload_sendbuffer_length

temp store: length of payload to send

xdata byte LL_tail_sendbuffer [LL_TAIL_SIZE]

temp store: tail to send

statistical variables

xdata unsigned long statsRfSlotsInSync

for a master: number of slots not in short search for beacon, for slave: number of slots in sync. only in these slots data can be sent

xdata unsigned long statsRfSlotsNeedToSend

those of the statsRfSlotsInSync where the node had to send something

xdata unsigned long statsRfArbitrationWon

those of the statsRfSlotsNeedToSend where arbitration was won

xdata unsigned long statsRfDataPacketsReceivedNotNeedingToSend

those of the statsRfSlotsNoNeedToSend where the node didn't detect another arbitration signal

Functions

void isr_timer0 ()

the "realtime"-part of the software.

void isr_timer2 ()

this is a dummy isr.

void main (void)

the "application level" part of the software.

Detailed Description

this is the stack file for particles based on the chipcon cc1010 all-in-one mobile chip.

it implements a new rf layer but leaves the upper layers compatible with other particles

Use 4 space tabs to ensure readability!

version 0.7, (c) Patrik Spieß, post@patrik-spiess.de, 2004-03-30

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. or see at the web page http://www.gnu.org/copyleft/gpl.html

Definition in file stackDistSync.c.

Define Documentation

#define DEBUG_USE_UART1_FOR_DUMPING

if defined, this switch activates output through uart1, otherwise output is directed to uart0 (default).
if DEBUG_USE_UART is not defined, this define is ignoredDefinition at line 85 of file stackDistSync.c.

#define DEBUG_VERIFY_SCRAMBLING

this switch turns on scrambling and tests the fitness of the scrambling macros
Definition at line 112 of file stackDistSync.c.

#define LL_STATE_NEED_TO_SEND BIN(00000100)

ll status bit: if 1, the data in the send buffer has to be sent.
the ll layer resets this bit, after successfully sending the packet or after reaching the slot limit.Definition at line 511 of file stackDistSync.c.

#define RF_ALONE_DEEP_SLEEP

this switch controls the actions taken if the node detects that it is alone.
if this switch is defined, the stack will halt the execution of the application and go into deep sleep (maximum energy saving). if it is not defined, the execution of the application will continue but outgoing packets are thrown away and the medium is not searched for incoming packets (medium power saving). if deep sleep is used, the node sleeps a random number of seconds seconds. the current number is provided by the function RFAloneRandomNumberOfSeconds(). if transmission suppression is used instead, the node stays in alone mode for a number of slots the current number is provided by the function RFAloneRandomNumberOfSlots().Definition at line 239 of file stackDistSync.c.

#define RF_ALONE_TEST_FAILED_THRESHOLD 167

how many slots without reception of a beacon must appear, before a node thinks it is alone.
Definition at line 226 of file stackDistSync.c.

#define RF_ALONE_TEST_RSSI_THRESHOLD 0xC0

the rssi threshold used for the alone test and traffic indication.
after the beacon in the beacon slot, every node that heard the beacon sends a signal at the rendezvous time RF_RENDEZVOUS_ALONE_TEST_X. by this method, the sending node knows if it is alone or not. the nodes that received the beacon already know that they are not alone: it heard a beacon, so it can't be alone.Definition at line 318 of file stackDistSync.c.

#define RF_ARBITRATION_RSSI_THRESHOLD 0x78

maximum rssi signal strength that may be read during arbitration to be able to send a packet.
if a signal with higher strength (lower ADC value) than this value is received, the node assumes, another node has a 1 and it backs off. this is not actually a dbm value. it is the raw value read from the analog digital converter. if the value is below this threshold, the signal strength is higher than a certain dbm value. e.g.: if the adc val is lower than 116, the dbm val is higher than -75 (recommended values by the chipcon application examples)# old val: 192=0xC0, 0xE0 new val: 151=0x97 (for the big boards) new val: 120=0x78 for the small partcBoards which report higher signal levels => lower rssi valuesDefinition at line 308 of file stackDistSync.c.

#define RF_BEACON_SEARCH_SLOTS_STARTUP 50

number of slots to search for am master at startup.
actually, a random number of 0-255 is added to this value to ensure that not all slaves synchronously want to become masters after a master gave up it's status.Definition at line 268 of file stackDistSync.c.
Referenced by isr_timer0().

#define RF_MAX_SYNC_JITTER 4000ul

the maximum time (im us) that a slave is waiting in a sync slot for the master sync signal.
the shorter this period, the less energy uses the node. but a shorter interval requires a more accurate synchronization.

a value of 15000ul leads to an actual detection period of 13ms
5769 should therefore lead to 5 ms
we use close sync now (+-10us), so just wait 500us / 576 - saves even more energy
Definition at line 255 of file stackDistSync.c.

#define RF_RENDEZVOUS_ALONE_TEST_HI 0xAA

value of timer register TH0 when traffic indication signal should be sent.
optimal values:

for 30 us beacon slot: 0xAA70
Definition at line 374 of file stackDistSync.c.

#define RF_RENDEZVOUS_ARBITRATION_START_HI 0x72

value of timer register TH0 when arbitration should begin.
optimal values:

for 25 us slot: 0x8B0A
for 30 us slot: 0x6F79
for distributed sync: 0x7214
Definition at line 336 of file stackDistSync.c.

#define RF_RENDEZVOUS_PACKET_START_HI 0x96

value of timer register TH0 when data or beacon send/receive should begin.
optimal values:

for 30 us slot:

rssi values dumped: 0x9E5D
no rssi dumping: 0x9161
for distributed sync 0x9687

Definition at line 327 of file stackDistSync.c.
Referenced by RFReceivePacket(), and RFSendPacket().

#define RF_RENDEZVOUS_TRAFFIC_INDICATION_HI 0xAE

value of timer register TH0 when traffic indication signal should be sent.
optimal values:

for 30 us beacon slot: 0xAE64
Definition at line 367 of file stackDistSync.c.

#define RF_SLOT_LENGTH_IN_US 36865ul

the slot length im us - according to the manual.
actually, this is the desired slot length multiplied with (approximately) 1,2956. a value of 36865ul leads to a period of 30000 usDefinition at line 261 of file stackDistSync.c.

#define RF_STATE_ALONE BIN(00000010)

rf status bit: if a master didn't here anything from another node for a certain number of times (normally some minutes) it sets this bit, and resets it at the first reception of a packet.
Definition at line 151 of file stackDistSync.c.

#define RF_STATE_IN_SYNC BIN(00000100)

rf status bit: the last synchronization was successful.
the node may only send, if this bit is 1Definition at line 157 of file stackDistSync.c.

#define RF_STATE_LONG_SEARCH_FOR_BEACON BIN(00010000)

rf status bit: the node is trying to become master.
for this it listens to the medium for a while until he is sure, there there is no other masterDefinition at line 170 of file stackDistSync.c.
Referenced by DebugDumpRfState(), isr_timer0(), and RFStart().

#define RF_STATE_SHORT_SEARCH_FOR_BEACON BIN(00100000)

rf status bit: a master node goes into this mode every time after sending the 100th beacon.
immediately after sending the sync, he listens to the channel if another master broadcasts a beacon. if he hears one, he gives up and turns into a slave, synchronizing to the other master. he listens at most for n slots until he is due to send the next sync packet.Definition at line 178 of file stackDistSync.c.
Referenced by DebugDumpRfState(), and isr_timer0().

#define RF_STATE_TRAFFIC_GROUP BIN(00001000)

rf status bit: if this bit is 0, the the stack is within an idle group (it may not send and it does not have to recieve packets).
if this bit is 1, it is within a traffic group (packets may be send and have to be received).Definition at line 164 of file stackDistSync.c.

#define RF_SYNC_ADDITIONAL_OFFSET 0xA3BD

additional offset added to start offset transmitted in beacon in us without this, the slave would wake up slightly to early.

if reciever wakes up to early decrease this value
if reciever wakes up to late increase this value
increase/decrease value by delay (in ms) / 0,81 566 for 76.8kBaud, Manchester. 422 for 76,8kBaud, NRZ, Scrambling und XOR-protection, without avg calculation new system: 0x8A35, 0x89B3 distribued sync with 1 additional byte time: 0x98A6 distributed sync: 0xA3BD
Definition at line 293 of file stackDistSync.c.

#define RF_SYNC_MAX_SLOT_COUNT 15

every RF_SYNC_MAX_SLOT_COUNT slots, a master sends a sync signal / a slave tries to receive a sync signal.
Definition at line 214 of file stackDistSync.c.

#define RF_USE_ALONE_DETECTION

if this switch is defined, the stack tries to detect the situation that a node is not connected to a network and use this information for saving energy.
Definition at line 220 of file stackDistSync.c.

Function Documentation

byte ACLAddData ( byte newByte )

adds one byte data into the ACL send buffer

Parameters:

newByte data byte to insert to the current ACL tuple

Returns:
0 if appending succeeded, 1 if packet is full, 2 if sending is busy
Definition at line 2789 of file stackDistSync.c.
References LL_payload_send, and LL_payload_send_length.

bool ACLAddNewType ( byte type_h,

byte type_l

)

adds a new type tuple to the payload

Returns:
0 if appending succeeded, 1 if packet is full, 2 if sending is busy
Definition at line 2769 of file stackDistSync.c.
References LL_payload_send, and LL_payload_send_length.

byte ACLAdressedDataIsNew ( )

Returns:
true if received packet is new and addressed to me
Definition at line 2960 of file stackDistSync.c.
References ACLDataIsNew(), ACLFoundReceivedType(), ACLGetReceivedData(), and ACLMatchesMyIP().

byte ACLAdressedDataIsNewNow ( )

Returns:
true if packet has been received in current slot and is addressed to me
Definition at line 2973 of file stackDistSync.c.
References ACLDataIsNewNow(), ACLFoundReceivedType(), ACLGetReceivedData(), and ACLMatchesMyIP().

byte ACLDataIsNew ( )

Returns:
true if data in receive buffer is "new", false otherwise
Definition at line 2939 of file stackDistSync.c.
References LLDataIsNew().

byte ACLDataReceivedInThisSlot ( )

Returns:
true if packet has been send and the subsequent slot has not yet started
Definition at line 2946 of file stackDistSync.c.
References LLSentPacketInThisSlot().

byte ACLFoundReceivedType ( byte type_h,

byte type_l

)

Parameters:

type_h the high byte of the acl type

type_l the low byte of the acl type

Returns:
true if a tuple of the given type is included in the last packet, false otherwise
Definition at line 2875 of file stackDistSync.c.
References ACLGetReceivedDataLength().

char ACLGetReceivedByte ( byte type_h,

byte type_l,

byte position

)

searches the first occurrence of type tuple and returns the position-th byte after that tuple

Returns:
single byte of last received packet on the given position after the first occurrence of the byte
Definition at line 2854 of file stackDistSync.c.
References LL_header_received, and LL_payload_received.

char* ACLGetReceivedData ( byte type_h,

byte type_l

)

Returns:
pointer to the ACL payload data of the given type in the last received packet or NULL if type was not found in packet
Definition at line 2836 of file stackDistSync.c.
References LL_header_received, and LL_payload_received.

signed char ACLGetReceivedDataLength ( byte type_h,

byte type_l

)

searches the last received packet for the given type and returns the data length of the entry found.

Returns:
see above
Definition at line 2821 of file stackDistSync.c.
References LL_header_received, and LL_payload_received.

byte ACLGetReceivedPayloadLength ( )

returns the number of payload bytes of the last packet received

Returns:
see above
Definition at line 2813 of file stackDistSync.c.
References LL_header_received.

byte ACLGetRemainingPayloadSpace ( )

returns the number of free bytes in the transmit buffer

Returns:
see above
Definition at line 2805 of file stackDistSync.c.
References LLGetRemainingPayloadSpace().

byte ACLGetSendSuccess ( )

returns the result of last packet transmission.
note that this value is valid for the last packet and is not set for the current packet in queue until sending is not busy any more.
Returns:
true if the last packet has been sent successfully, false otherwise
Definition at line 2696 of file stackDistSync.c.
References LLGetSendSuccess().

byte ACLMatchesMyIP ( char * buffer,

byte start

)

checks, if buffer holds my IP

Parameters:

buffer buffer in which to search

start start offset where to begin the search

Returns:
true if given buffer on the given position matches own ip, false otherwise
Definition at line 2706 of file stackDistSync.c.
References LL_header_sendbuffer.

byte ACLProcessControlMessages ( )

internal: is called if control msg is there

Returns:
one if there was a control msg, the return value is no longer used.
Definition at line 2601 of file stackDistSync.c.
References ACL_CONTROL_MESSAGES_TIMEOUT, ACL_TYPE_ACM_H, ACL_TYPE_ACM_L, ACLAbortSending(), ACLMatchesMyIP(), LL_header_receivebuffer, LL_payload_receivebuffer, LL_payload_send, LL_payload_send_length, LL_STATE_CTRL_MESSAGE_INSERTED, LLSendingBusy(), LLSendPacket(), llState, and RFStop().

byte ACLReceiveBufferLocked ( )

Returns:
true if receivebuffer is locked, false otherwise
Definition at line 2917 of file stackDistSync.c.
References LLReceiveBufferLocked().

byte ACLSendPacket ( byte slot_timeout )

queues a packet for transmission

Parameters:

slot_timeout number of slots the packet is tried to be sent

Returns:
true, if packed was queued, false if sending is busy or connection is off or anything else goes wrong
Definition at line 2739 of file stackDistSync.c.
References LLSendPacket().

byte ACLSendPacketAdressed ( nodeAddrType * address,

byte timeout

)

sends out the current packet with a target ID

Parameters:

address pointer to an address data structure

timeout how many slots the packet is tried to be sent until giving up

Definition at line 2989 of file stackDistSync.c.
References NODE_ADDR_STUCT::a1, NODE_ADDR_STUCT::a2, NODE_ADDR_STUCT::a3, NODE_ADDR_STUCT::a4, NODE_ADDR_STUCT::a5, NODE_ADDR_STUCT::a6, NODE_ADDR_STUCT::a7, NODE_ADDR_STUCT::a8, ACLAddData(), ACLAddNewType(), ACLGetRemainingPayloadSpace(), ACLSendPacket(), and nodeAddrType.

byte ACLSentPacketInThisSlot ( )

Returns:
true after a packet was sent and before the start of the next slot, false otherwise
Definition at line 2895 of file stackDistSync.c.
References LLSentPacketInThisSlot().

void ACLSetControlMessagesBehaviour ( boolean ignore,

boolean pass

)

note that the settings are independent.
you may set ignore to true and pass to false having the effect that control messages are completely thrown away (not processed and filtered). if you set ignore to false and pass to true, they are not processed and copied as payload.
Parameters:

ignore if true, all control messages are not processed, otherwise they are processed normally

pass if true, all control messages are copied to receivebuffer for application, if false, they are filtered out

Definition at line 2886 of file stackDistSync.c.
References ACLSetControlMessagesBehaviour().

byte ACLSubscribe ( byte LL_type_h,

byte LL_type_l

)

adds a type to the subscription list

Parameters:

LL_type_h the high byte of the acl type

LL_type_l the low byte of the acl type

Returns:
TRUE if action succeeded, false otherwise
Definition at line 2508 of file stackDistSync.c.
References ACL_SUBSCRIPTIONLIST_LENGTH.

byte ACLUnsubscribe ( byte LL_type_h,

byte LL_type_l

)

deletes a type out of the subscription list

Parameters:

LL_type_h the high byte of the acl type

LL_type_l the low byte of the acl type

Returns:
TRUE if the type was found and deleted, false otherwise
Definition at line 2531 of file stackDistSync.c.
References ACL_SUBSCRIPTIONLIST_LENGTH.

byte ACLVerifySubscription ( byte type_h,

byte type_l

)

checks if a subscription is there

Parameters:

type_h the high byte of the acl type

type_l the low byte of the acl type

Returns:
true if the given type subscribed, false otherwise
Definition at line 2587 of file stackDistSync.c.
References ACL_SUBSCRIPTIONLIST_LENGTH.

void DebugBuildTestPacketACL ( )

builds a test packet.
Definition at line 741 of file stackDistSync.c.

void DebugDumpReceivedAclPacket ( )

dumps a representation of the last received packet payload (stored in LL_payload_received) to the serial port.
Definition at line 699 of file stackDistSync.c.
References ACLLockReceiveBuffer(), LL_header_received, LL_payload_received, LL_payload_received_length, and putchar().
Referenced by main().

void isr_timer0 ( )

the "realtime"-part of the software.
here all sending and receiving of content is done. ISR (interrupt service routine) for timer 3, priority 10. The interrupt must be cleared by software Definition at line 3015 of file stackDistSync.c.
References DebugDumpRfState(), LL_payload_received_length, LL_payload_sendbuffer_length, LL_STATE_CTRL_MESSAGE_INSERTED, LL_STATE_NEED_TO_SEND, LL_STATE_NEW_DATA, LL_STATE_PACKET_JUST_RECEIVED, LL_STATE_PACKET_JUST_SENT, LL_STATE_RECEIVE_BUFFER_LOCKED, LL_STATE_SEND_SUCCESS, llState, moduloTimer0, putchar(), RF_ALONE_TEST_FAILED_THRESHOLD, RF_BEACON_SEARCH_SLOTS_STARTUP, RF_MASTER_SEARCH_SLOTS_AFTER_ALONE, RF_NEW_RANDOM_BYTE, RF_STATE_ALONE, RF_STATE_LONG_SEARCH_FOR_BEACON, RF_STATE_MASTER, RF_STATE_RUNNING, RF_STATE_SHORT_SEARCH_FOR_BEACON, RF_STATE_TRAFFIC_GROUP, RF_SYNC_MAX_SLOT_COUNT, RFAloneRandomNumberOfSeconds(), RFAloneRandomNumberOfSlots(), RFAloneTest(), RFArbitration(), RFLongSearchForBeacon(), RFLowPowerSleep(), RFReceivePacket(), RFSendPacket(), RFShallISendSync(), RFShortSearchForBeacon(), rfSlotsWithoutSignalReceived, rfState, statsRfArbitrationWon, statsRfDataPacketsReceivedNotNeedingToSend, statsRfSlotsInSync, and statsRfSlotsNeedToSend.

void isr_timer2 ( )

this is a dummy isr.
nothing is done. it is used to wake up the node from idle mode in low frequency mode. this is done in RFLowPowerSleep(). Definition at line 3228 of file stackDistSync.c.

void LLAbortSending ( )

unqueues the current packet.
i.e. the process of sending a packet is being aborted.Definition at line 2227 of file stackDistSync.c.
References LL_STATE_CTRL_MESSAGE_INSERTED, LL_STATE_NEED_TO_SEND, LL_STATE_SEND_SUCCESS, LLSendingBusy(), and llState.

unsigned short LLCalcCRC16 ( byte * header_data,

byte * payload_data,

byte payload_size

)

calculates the crc-16 checksum over the rf packet (ll header + payload)

Parameters:

header_data header of the current packet

payload_data payload of the current packet

payload_size as the name suggests

Returns:
checksum
Definition at line 2345 of file stackDistSync.c.

byte LLDataIsNew ( )

Returns:
true if new data has received and stored in the receive buffer after the last call to LLSetDataToOld(), false otherwise.
Definition at line 2319 of file stackDistSync.c.
References LL_STATE_NEW_DATA, and llState.

byte LLGetFieldStrength ( )

Returns:
field strength at which packets are sent out (0-255)
Definition at line 2326 of file stackDistSync.c.
References rfFieldStrength.

byte LLGetRemainingPayloadSpace ( )

Returns:
number of payload byte left in current packet
Definition at line 2425 of file stackDistSync.c.
References LL_payload_send_length.

byte LLGetSendSuccess ( )

Returns:
true, if the last sending was successful, false otherwise. note that this value represents the success of the last sending procedure, even if we are already in the next one.
Definition at line 2265 of file stackDistSync.c.
References LL_STATE_SEND_SUCCESS, and llState.

byte LLIsActive ( )

Returns:
true, if the ll layer is running, false otherwise
Definition at line 2272 of file stackDistSync.c.
References LL_STATE_RUNNING, and llState.

void LLLockReceiveBuffer ( )

locks the receive buffer, i.e.
no packets are received by the rf layer until it is unlocked. useful if the data received needs time-consuming processing.Definition at line 2287 of file stackDistSync.c.
References LL_STATE_RECEIVE_BUFFER_LOCKED, LLSetDataToOld(), and llState.

byte LLReceiveBufferLocked ( )

Returns:
true if receive buffer is locked, false otherwise
Definition at line 2295 of file stackDistSync.c.
References LL_STATE_RECEIVE_BUFFER_LOCKED, and llState.

void LLReleaseReceiveBuffer ( )

unlocks the receive buffer, i.e.
new packets can be receivedDefinition at line 2302 of file stackDistSync.c.
References LL_STATE_RECEIVE_BUFFER_LOCKED, LLSetDataToOld(), and llState.

byte LLSendingBusy ( )

Returns:
true if the ll layer is busy sending or preparing to send, false otherwise
Definition at line 2257 of file stackDistSync.c.
References LL_STATE_NEED_TO_SEND, and llState.

byte LLSendPacket ( byte slot_limit )

prepares the LL header and instructs the rf layer to send the packet out (via flag).
this function is non-blocking.
Returns:
true, if queueing of the packet succeeded, false otherwise.
Definition at line 2382 of file stackDistSync.c.
References LL_header_sendbuffer, LL_payload_send, LL_payload_send_length, LL_payload_sendbuffer, LL_payload_sendbuffer_length, LL_sequence_no, LL_STATE_NEED_TO_SEND, LL_tail_sendbuffer, LLCalcCRC16(), llState, RF_STATE_RUNNING, rfFieldStrength, and rfState.

byte LLSentPacketInThisSlot ( )

Returns:
true if the packet was just sent, false otherwise
Definition at line 2433 of file stackDistSync.c.
References LL_STATE_PACKET_JUST_SENT, and llState.

void LLSetDataToNew ( )

sets the "new data flag".
Definition at line 2310 of file stackDistSync.c.
References LL_STATE_NEW_DATA, and llState.

void LLSetDataToOld ( )

resets the "new data flag".
it will be reset again by the rf layer if new data has arrived.Definition at line 2279 of file stackDistSync.c.
References LL_STATE_NEW_DATA, and llState.

void LLSlotEnd ( )

i guess this function is called at the end of the ISR before returning to "application level".
it checks if the packet was finally sent and sets the correct ll status.Definition at line 2219 of file stackDistSync.c.

void main ( void )

the "application level" part of the software.
this method runs all tasks that are not time critical. Definition at line 3239 of file stackDistSync.c.
References ACLAddData(), ACLAddNewType(), ACLDataIsNew(), ACLGetSendSuccess(), ACLLockReceiveBuffer(), ACLReleaseReceiveBuffer(), ACLSendingBusy(), ACLSendPacket(), ACLStartUp(), ACLSubscribeAll(), DebugDumpReceivedAclPacket(), LL_STATE_SEND_SUCCESS, LLSentPacketInThisSlot(), llState, ParticleInit(), putchar(), and RF_LOW_POWER_SLEEP_UNTIL_NEXT_SLOT.

void putchar ( char c )

classic putchar function that is used to output a character to the "screen", in our case the serial port.
Definition at line 728 of file stackDistSync.c.

byte RFAloneRandomNumberOfSeconds ( )

returns the number of seconds that the node should stay in deep sleep when it detects that it is alone.
this value should be random between a minimum and a maximum number. suggested boundaries are 10 and 26. this function is only used when RF_ALONE_DEEP_SLEEP is defined.
Returns:
see above
Definition at line 1757 of file stackDistSync.c.
References RF_NEW_RANDOM_BYTE.

unsigned short RFAloneRandomNumberOfSlots ( )

returns the number of slots that the node should stay alone mode (suppressing communication) when it detects that it is alone.
this value should be random between a minimum and a maximum number. suggested boundaries are 333 and 867. this function is only used when RF_ALONE_DEEP_SLEEP is not defined.
Returns:
see above
Definition at line 1769 of file stackDistSync.c.
References RF_NEW_RANDOM_BYTE.

bool RFAloneTest ( bool send )

this method is to be called in a sync slot immediately after sending/receiving of the sync packet has occurred.
depending on if the node is a master or a slave, it waits until a given rendezvous time and then sends a signal respectively measures the signal strength using the same technique like in RFArbitration().

Returns:
true if the node is a master and no other node has been detected for a number of sync slots, false otherwise.
Definition at line 1719 of file stackDistSync.c.
References RF_ALONE_TEST_RSSI_THRESHOLD, RF_RENDEZVOUS_ALONE_TEST_HI, RF_SET_MODE_SLEEP, and RFArbitrationBit().
Referenced by isr_timer0().

bool RFArbitration ( bool tryToObtainMediaAccess,

bool syncPrio

)

tries to get media access through the can arbitration process.
the measured time between switching on the rf for sending and getting a pll lock is ~450 us, twice as long as the manual says (250 us).
the first arbitration slice is used to determine if the packet to be sent or received is a beacon. if there is a signal on the medium in the first slice, it is a beacon, otherwise it is a data packet.
if rf state is not traffic group (i.e. traffic indication does not expect a packet and may not send one) the arbitration process is shortened: only sync arbitration is done. if sync signal was found in the 1st slice, true is returned, false otherwise. if syncPrio (2nd param) is true, a complete arbitration is done.

Parameters:

tryToObtainMediaAccess if this param is true, a random number is drawn for arbitration, otherwise 0 is taken, so only medium sensing is done

syncPrio if this param is true, a signal will be sent in the sync arbitration slice, that is the first slice before the regular slices

Returns:
bool true if no activity was found on the medium (i.e. no "ones" of other nodes were heard during own "zeros"). if tryToObtainMediaAccess is TRUE this means that the node won the arbitration and may send. FALSE if other nodes trying to send were detected
Definition at line 1522 of file stackDistSync.c.
References arbitrationBad, arbitrationGood, BIN, bit_test, RF_ARBITRATION_RSSI_THRESHOLD, RF_ARBITRATION_TIMER_TICS_OTHER_PERIODS, RF_NEW_RANDOM_BYTE, RF_RENDEZVOUS_ARBITRATION_START_HI, RF_SET_MODE_SLEEP, RF_STATE_TRAFFIC_GROUP, RFArbitrationBit(), rfState, and rssiSamples.

byte RFArbitrationBit ( bool sendOrListen,

byte syncTimeH,

byte syncTimeL

)

does the arbitration for one arbitration slice.

Parameters:

sendOrListen true if a signal should be sent, false if node should listen

syncTimeH high byte of timer0 value to wait for

syncTimeL low byte of timer0 value to wait for

Returns:
if sendOrListen was false: true if a signal was heard, false if not. always true if sendOrListen was true
Definition at line 1389 of file stackDistSync.c.
References BIN, RFSetModeReceive(), RFSetModeTransmit(), and WAIT_FOR_TIMER0_EXACT.

byte RFArbitrationBitDebug ( bool sendOrListen,

byte syncTimeH,

byte syncTimeL

)

does the arbitration for one arbitration slice.

Parameters:

sendOrListen true if a signal should be sent, false if node should listen

syncTimeH high byte of timer0 value to wait for

syncTimeL low byte of timer0 value to wait for

Returns:
if sendOrListen was false: true if a signal was heard, false if not. always true if sendOrListen was true
Definition at line 1463 of file stackDistSync.c.
References BIN, RF_SET_MODE_SLEEP, rfMaxTimerValue, RFSetModeReceive(), and RFSetModeTransmit().

byte RFDescramble ( byte b )

this function wraps the marcro RF_SCRAMBLE.
previously, this was "called" directly in RFReceivePacket for efficiency reasons, but there seems to be enough time to call it as a function, which increases run-time-overhead but reduces binary size by 13 percent.Definition at line 1879 of file stackDistSync.c.
References rfScramblerReg.

bool RFLongSearchForBeacon ( unsigned short numTries )

does a long search for a beacon.
this achieve by searching for a beacon for a time which is a multiple m of slot length. m is at least the value specified by RF_BEACON_SEARCH_SLOTS_STARTUP plus a random value (0-255). the random part is added to ensure that if a master gives up it's role not all slaves want to become master at the same time.
Returns:
TRUE if a beacon was found, FALSE otherwise
Definition at line 2093 of file stackDistSync.c.
References periodDataSlot, and RFReceivePacket().
Referenced by isr_timer0().

void RFLowPowerSleep ( byte sleepTime )

sends the node into power-saving mode for 10-26 seconds. this is done by turning on the 32KHz clock, switching off the 14MHz clock and switching the core to the low frequency clock. the node stays in low freq mode for a given number of seconds and then switches back to high freq mode and returns from the function.

Parameters:

sleepTime number of seconds to sleep

Definition at line 1782 of file stackDistSync.c.

unsigned short RFReceivePacket ( xdata TIMER_DATA * timeOutPeriodData,

bool waitForPacketsRendevouz,

bool ignoreDataPackets

)

the general function to receive a packet.
the incoming packet is checked against the ACL subscription list. if the acl type in the RF Header does not match the subscriptions, the transceiver is powered off and 0 is returned. the packet contents is written into LL_header_receivebuffer and LL_payload_receivebuffer. if it matches the subscriptions, both are copied into LL_header_received and LL_payload_received and LL_payload_received_length is set to the correct length.
the function tries not to block timer0 interrupt: when timer0 interrupt is enabled, the function not only aborts if timer2 overflows (after the time given by param timeOutPeriodData), but also if there are only 200us left till the next timer0 tick begins. this allows for a simple RFShortSearchForBeacon() function. uses timer2 which must be available!
the function returns an unsigned short:

low byte: kind of packet received.

0: no packet or checksum error
1: regular packet
2: beacon

high byte:

if the low byte is 1, the received payload length, otherwise 0.

Parameters:

timeOutPeriodData precalculated timeout timer data. if no sync is received during timer runtime, receiving is aborted.

waitForPacketsRendevouz if true, the function waits for the start data packet rendezvous before receiving

ignoreDataPackets if true, only sync packets are received and data packets discarded. this is useful if the receive buffer is locked.

Returns:
see above
Definition at line 1126 of file stackDistSync.c.
References ACL_SUBSCRIPTIONLIST_LENGTH, LL_header_receivebuffer, LL_header_received, LL_payload_receivebuffer, LL_payload_received, LL_tail_receivebuffer, LL_tail_received, LLCalcCRC16(), RF_PREAMBLE_LENGTH_RX, RF_RENDEZVOUS_PACKET_START_HI, RF_SET_MODE_SLEEP, RF_SLOT_500_US_LEFT, RF_SPI_RECEIVE_BYTE, RFDescramble(), RFSetModeReceive(), and WAIT_FOR_TIMER0_EXACT.

byte RFScramble ( byte b )

this function wraps the marcro RF_SCRAMBLE.
previously, this was "called" directly in RFSendPacket for efficiency reasons, but there seems to be enough time to call it as a function, which increases run-time-overhead but reduces binary size by 13 percent.Definition at line 1864 of file stackDistSync.c.
References rfScramblerReg.

bool RFSendPacket ( bool sync )

sends length chars of the packetContent string in an rf packet.
if param sync is true, a beacon is sent. if it is false, a normal packet will be sent. in that case, the packet content is taken out of LL_header_sendbuffer and LL_payload_sendbuffer. the length of the payload to send is taken out of LL_payload_sendbuffer_length.
Parameters:

sync true if beacon should be sent, false (default) otherwise

Returns:
bool false if data packet and transmission during backoff so that packet could not be sent, false otherwise
Definition at line 1898 of file stackDistSync.c.
References BIN, LL_header_sendbuffer, LL_payload_sendbuffer, LL_payload_sendbuffer_length, LL_tail_sendbuffer, RF_PREAMBLE_LENGTH_TX, RF_RENDEZVOUS_PACKET_START_HI, RF_SET_MODE_SLEEP, RF_SPI_SEND_BYTE, RF_SYNC_ADDITIONAL_OFFSET, RFScramble(), RFSendPacket(), RFSetModeTransmit(), and WAIT_FOR_TIMER0_EXACT.

void RFSetModeReceive ( )

faster version of the halRFSetRxTxOff function to start receiving prior execution of halRFSetRxTxOff() is required.
Definition at line 1049 of file stackDistSync.c.
References RF_CALDATA, and RF_SETTINGS.

void RFSetModeTransmit ( )

faster version of the halRFSetRxTxOff function to start sending.
does not set all values. prior execution of halRFSetRxTxOff() is required.Definition at line 1010 of file stackDistSync.c.
References RF_CALDATA, RF_SETTINGS, and rfFieldStrength.

bool RFShallISendSync ( byte slotCount )

returns true with the following probabilities, depending on the given slot number.
the node should try to send a beacon if this function (fed with the current slot number) returns true.
Slot # Probability 0-9 0 10 or 20 1/1024 11 or 19 1/256 12 or 18 1/64 13 or 17 1/16 14 or 16 1/4 15 1/2
Returns:
see above
Definition at line 1836 of file stackDistSync.c.
References RF_NEW_RANDOM_BYTE.
Referenced by isr_timer0().

bool RFShortSearchForBeacon ( )

does a short search for beacon.
from time to time the node searches an entire sync period (i.e. the period between two beacon slots) if he hears
Returns:
TRUE if a beacon was found, FALSE otherwise
Definition at line 2124 of file stackDistSync.c.
References periodDataSlot, and RFReceivePacket().
Referenced by isr_timer0().

Variable Documentation

data volatile byte llState = 0

byte that holds the current rf state.

bit 0 (LL_STATE_SEND_SUCCESS)

1= last packet sent successfully, 0= last packet not sent successfully (only valid if LL_STATE_NEED_TO_SEND=0)

bit 1 (LL_STATE_CTRL_MESSAGE_INSERTED)

1= a packet in send buffer has been replaced by a control message, 0= no control message has been inserted

bit 2 (LL_STATE_NEED_TO_SEND)

1= send buffer needs to be sent, 0= no need to send the send buffer, the flag is reset after a packet has been successfully sent

bit 3 (LL_STATE_RECEIVE_BUFFER_LOCKED)

1= buffer is locked so that no more packets will be received, 0= buffer is not locked

bit 4 (LL_STATE_NEW_DATA)

1= data in receive buffer is new since last setting the flag to 0, 0= data in the receive buffer is not new since last reset

bit 5 (LL_STATE_PACKET_JUST_SENT) 1= a packet was sent in the current slot, 0= no packet was sent in the current slot
bit 6 (LL_STATE_PACKET_JUST_RECEIVED)

1= a packet was received in the current slot, 0= no packet was received in the current slot

bit 7 (LL_STATE_RUNNING)

1= rf layer is running, 0= rf layer is stopped

Definition at line 542 of file stackDistSync.c.

RF_RXTXPAIR_SETTINGS code RF_SETTINGS

Initial value:
{ 0xA0, 0x2F, 0x52, 0x76, 0x00, 0x00, 0x58, 0x7A, 0x8D, 0x01, 0xAB, 0x40, 0x30, 0x6C, 0xF3, 0x32, 0xA0, 0x00, 0x00, }
// X-tal frequency: 14.745600 MHz // RF frequency A: 871.042000 MHz Rx // RF frequency B: 871.042000 MHz Tx // RX Mode: Low side LO // Frequency separation: 64 kHz // Data rate: 76.8 kBaud // Data Format: NRZ // RF output power: -5 dBm // IF/RSSI: RSSI Enabled
Definition at line 432 of file stackDistSync.c.

xdata byte rfFieldStrength

holds the value of the currently used field strength.
the var is set by LLGetFieldStrength() and read by LLGetFieldStrength(). The upper nibble controls the high power array of the transmitter, the lower nibble the low power array. sensible values are: 00, 01, 02, .., 0F, 10, 20, 30, ..., F0.
value output power consumption 0F -5db 27mA F0 3db 35mA
Definition at line 459 of file stackDistSync.c.

xdata unsigned short rfMaxTimerValue

this is a scratch variable that may hold the maximum timer value of timer 0 if timer0 is measured on a certain place in the program.
Definition at line 477 of file stackDistSync.c.
Referenced by RFArbitrationBitDebug(), and RFStart().

data byte rfScramblerReg = BIN(01101100)

current value of the scrambler register which is used to generate a dc-free code with limited run-length for rf transmission.
Definition at line 387 of file stackDistSync.c.

data volatile byte rfState = 0

byte that holds the current rf state.

bit 0 (RF_STATE_MASTER)

1= master, 0= slave

bit 1 (RF_STATE_ALONE)

1= alone, 0= not alone

bit 2 (RF_STATE_IN_SYNC)

1= in sync, 0= not in sync

bit 3 (RF_STATE_TRAFFIC_GROUP)

1= stack is in a traffic group, 0= stack is in an idle group

bit 4 (RF_STATE_LONG_SEARCH_FOR_BEACON)

1= doing long sync, 0= not doing long sync

bit 5 (RF_STATE_SHORT_SEARCH_FOR_BEACON)

1= doing short search for beacon, 0= not doing short search for beacon

bit 6 ()

1= , 0=

bit 7 (RF_STATE_RUNNING)

1= rf layer is running, 0= rf layer is stopped

Definition at line 202 of file stackDistSync.c.

data unsigned short tEndAvg = 0

the average timer value on the master after sending the beacon.
this value is measured by the master and sent to the slave in the sync packet. the slave adjusts his timer to this value after receiving it.Definition at line 397 of file stackDistSync.c.

Generated on Fri Aug 27 10:04:05 2004 for Cheap Sensor Network by

1.3.8


Debug switches
#define	DEBUG_USE_UART
	this switch activates debug messages that are sent through a serial port
#define	DEBUG_USE_UART1_FOR_DUMPING
	if defined, this switch activates output through uart1, otherwise output is directed to uart0 (default).
#define	DEBUG_VERIFY_SCRAMBLING
	this switch turns on scrambling and tests the fitness of the scrambling macros
RF defines and variables
#define	RF_STATE_MASTER BIN(00000001)
	this bit is not used in distributed sync mode
#define	RF_STATE_ALONE BIN(00000010)
	rf status bit: if a master didn't here anything from another node for a certain number of times (normally some minutes) it sets this bit, and resets it at the first reception of a packet.
#define	RF_STATE_IN_SYNC BIN(00000100)
	rf status bit: the last synchronization was successful.
#define	RF_STATE_TRAFFIC_GROUP BIN(00001000)
	rf status bit: if this bit is 0, the the stack is within an idle group (it may not send and it does not have to recieve packets).
#define	RF_STATE_LONG_SEARCH_FOR_BEACON BIN(00010000)
	rf status bit: the node is trying to become master.
#define	RF_STATE_SHORT_SEARCH_FOR_BEACON BIN(00100000)
	rf status bit: a master node goes into this mode every time after sending the 100th beacon.
#define	RF_STATE_RUNNING BIN(10000000)
	rf status bit: rf layer is running
#define	RF_SYNC_MAX_SLOT_COUNT 15
	every RF_SYNC_MAX_SLOT_COUNT slots, a master sends a sync signal / a slave tries to receive a sync signal.
#define	RF_USE_ALONE_DETECTION
	if this switch is defined, the stack tries to detect the situation that a node is not connected to a network and use this information for saving energy.
#define	RF_ALONE_TEST_FAILED_THRESHOLD 167
	how many slots without reception of a beacon must appear, before a node thinks it is alone.
#define	RF_ALONE_DEEP_SLEEP
	this switch controls the actions taken if the node detects that it is alone.
#define	RF_PREAMBLE_LENGTH_TX 20
	the number of preamble bytes that are sent before any RF packet on send
#define	RF_PREAMBLE_LENGTH_RX 20
	the number of preamble bytes need to be detected before any RF packen on receive
#define	RF_MAX_SYNC_JITTER 4000ul
	the maximum time (im us) that a slave is waiting in a sync slot for the master sync signal.
#define	RF_SLOT_LENGTH_IN_US 36865ul
	the slot length im us - according to the manual.
#define	RF_BEACON_SEARCH_SLOTS_STARTUP 50
	number of slots to search for am master at startup.
#define	RF_MASTER_SEARCH_SLOTS_AFTER_ALONE 167
	number of slots to when waking up from alone low power sleep
#define	RF_MAX_FAILED_SYNC_COUNT 10
	after not being able to receive a sync signal for RF_MAX_FAILED_SYNC_COUNT times, a slave goes into status RF_STATE_SYNC_MASTER_LONG_TEST
#define	RF_SYNC_ADDITIONAL_OFFSET 0xA3BD
	additional offset added to start offset transmitted in beacon in us without this, the slave would wake up slightly to early.
#define	RF_ARBITRATION_RSSI_THRESHOLD 0x78
	maximum rssi signal strength that may be read during arbitration to be able to send a packet.
#define	RF_ALONE_TEST_RSSI_THRESHOLD 0xC0
	the rssi threshold used for the alone test and traffic indication.
#define	RF_RENDEZVOUS_PACKET_START_HI 0x96
	value of timer register TH0 when data or beacon send/receive should begin.
#define	RF_RENDEZVOUS_ARBITRATION_START_HI 0x72
	value of timer register TH0 when arbitration should begin.
#define	RF_ARBITRATION_TIMER_TICS_OTHER_PERIODS 0x390
	how many timer0 tics between rendezvous points optimal value for 76.8 kBaud Manchester: 0x1EA for 2 samples / 13 bit sent 0x24C for 3 samples / 20 bit sent optimal value for 76.8 kBaud NRZ: 0x3D8 for 3 samples / 20 bit sent (for testing and rssi dumping use 0x500) 0x358 - 0x380
#define	RF_BUFFER_SIZE 64
	size of the sending and reception buffer
#define	RF_RENDEZVOUS_TRAFFIC_INDICATION_HI 0xAE
	value of timer register TH0 when traffic indication signal should be sent.
#define	RF_RENDEZVOUS_ALONE_TEST_HI 0xAA
	value of timer register TH0 when traffic indication signal should be sent.
data volatile byte	rfState = 0
	byte that holds the current rf state.
data byte	rfScramblerReg = BIN(01101100)
	current value of the scrambler register which is used to generate a dc-free code with limited run-length for rf transmission.
data unsigned long	randomNumberReg
	random number generator register
data unsigned short	tEndAvg = 0
	the average timer value on the master after sending the beacon.
xdata TIMER_DATA	periodDataSlot
	the calculated periods for the timer registers
xdata signed short	moduloTimer0
	the modulo word for timer adjustment of timer 0
xdata byte	rssiSamples [16]
	the rssi samples acquired during arbitration
unsigned short	arbitrationGood = 0
	statistic counter: number of times arbitration succeeded (media access granted)
unsigned short	arbitrationBad = 0
	statistic counter: number of times arbitration failed (media access denied)
RF_RXTXPAIR_SETTINGS code	RF_SETTINGS
xdata RF_RXTXPAIR_CALDATA	RF_CALDATA
	Calibration data.
xdata byte	rfFieldStrength
	holds the value of the currently used field strength.
xdata unsigned short	rfMaxTimerValue
	this is a scratch variable that may hold the maximum timer value of timer 0 if timer0 is measured on a certain place in the program.
LL defines and variables
#define	LL_PROTOCOL_VERSION 4
	the protocol version
#define	LL_CRC16_POLY 0x1021
	check polynom for crc 16
#define	LL_CRC16_INIT 0xFFFF
	initial value of the crc16 register
#define	LL_CRC_OK 0
	modulo for correct crc reception (zero)
#define	LL_STATE_SEND_SUCCESS BIN(00000001)
	true if the last packet was sent successfully, false otherwise. updated when LL_STATE_NEED_TO_SEND is reset.
#define	LL_STATE_CTRL_MESSAGE_INSERTED BIN(00000010)
	true if packet in send buffer has been replaced by a control message
#define	LL_STATE_NEED_TO_SEND BIN(00000100)
	ll status bit: if 1, the data in the send buffer has to be sent.
#define	LL_STATE_RECEIVE_BUFFER_LOCKED BIN(00001000)
	true if receive buffer is locked, false otherwise
#define	LL_STATE_NEW_DATA BIN(00010000)
	true if new data has arrived in the receive buffer after the last time this flag was set to 0, false otherwise
#define	LL_STATE_PACKET_JUST_SENT BIN(00100000)
	true if a packet was sent in the current slot, false otherwise
#define	LL_STATE_PACKET_JUST_RECEIVED BIN(01000000)
	true if a packet was received in the current slot, false otherwise
#define	LL_STATE_RUNNING BIN(10000000)
	true if ll layer is running, false otherwise
xdata byte	LL_sequence_no
	current LL sequence number
data volatile byte	llState = 0
	byte that holds the current rf state.
ACL defines and variables
#define	ACL_SUBSCRIPTIONLIST_LENGTH 8
	length of the subscription list, must be dividable by 4
#define	ACL_CONTROL_MESSAGES_TIMEOUT 30
	timeout in slots for control messages
#define	ACL_TYPE_ACM_H ACL_TYPE_ACM_HI
	synonym
#define	ACL_TYPE_ACM_L ACL_TYPE_ACM_LO
	synonym
Helper functions
void	DebugDumpRfState ()
	sends a nice representation of the the current rf status to uart
void	DebugDumpReceivedAclPacket ()
	dumps a representation of the last received packet payload (stored in LL_payload_received) to the serial port.
void	putchar (char c)
	classic putchar function that is used to output a character to the "screen", in our case the serial port.
void	DebugBuildTestPacketACL ()
	builds a test packet.
"PIC" Layer
actually CC1010 layer - board setup. sets up the board: LEDs, watchdog timer, memory access, serial port
void	ParticleInit ()
	sets up the board: LEDs, watchdog timer, memory access, serial port
byte	AppSelfTest (char *result)
RF Layer Functions
void	RFInit ()
	calibrates the transceiver. calculates timer periods needed for rf.
void	RFStart ()
	starts the timer. this turns on receiving, sending and sync. turns on rssi.
void	RFStop ()
	stops the timer.
void	RFSetModeTransmit ()
	faster version of the halRFSetRxTxOff function to start sending.
void	RFSetModeReceive ()
	faster version of the halRFSetRxTxOff function to start receiving prior execution of halRFSetRxTxOff() is required.
void	RFInitRandom ()
	gets a true random number for initialization of the random number generator
unsigned short	RFReceivePacket (xdata TIMER_DATA *timeOutPeriodData, bool waitForPacketsRendevouz, bool ignoreDataPackets)
	the general function to receive a packet.
byte	RFArbitrationBit (bool sendOrListen, byte syncTimeH, byte syncTimeL)
	does the arbitration for one arbitration slice.
byte	RFArbitrationBitDebug (bool sendOrListen, byte syncTimeH, byte syncTimeL)
	does the arbitration for one arbitration slice.
bool	RFArbitration (bool tryToObtainMediaAccess, bool syncPrio)
	tries to get media access through the can arbitration process.
bool	RFAloneTest (bool send)
	this method is to be called in a sync slot immediately after sending/receiving of the sync packet has occurred.
byte	RFAloneRandomNumberOfSeconds ()
	returns the number of seconds that the node should stay in deep sleep when it detects that it is alone.
unsigned short	RFAloneRandomNumberOfSlots ()
	returns the number of slots that the node should stay alone mode (suppressing communication) when it detects that it is alone.
void	RFLowPowerSleep (byte sleepTime)
	sends the node into power-saving mode for 10-26 seconds. this is done by turning on the 32KHz clock, switching off the 14MHz clock and switching the core to the low frequency clock. the node stays in low freq mode for a given number of seconds and then switches back to high freq mode and returns from the function.
bool	RFShallISendSync (byte slotCount)
	returns true with the following probabilities, depending on the given slot number.
byte	RFScramble (byte b)
	this function wraps the marcro RF_SCRAMBLE.
byte	RFDescramble (byte b)
	this function wraps the marcro RF_SCRAMBLE.
bool	RFSendPacket (bool sync)
	sends length chars of the packetContent string in an rf packet.
bool	RFLongSearchForBeacon (unsigned short numTries)
	does a long search for a beacon.
bool	RFShortSearchForBeacon ()
	does a short search for beacon.
LL Layer Functions
byte	LLGetIDFromHardware ()
	reads particle address from flash
void	LLInit ()
	initializes the ll layer (and the lower layers)
void	LLStart ()
	starts the ll layer and the rf layer
void	LLStop ()
	stops the ll layer and the rf layer
void	LLSlotEnd ()
	i guess this function is called at the end of the ISR before returning to "application level".
void	LLAbortSending ()
	unqueues the current packet.
void	LLSetSendingSuccess ()
	sets the rfState and llState bits to their sending success value
byte	LLSendingBusy ()
byte	LLGetSendSuccess ()
byte	LLIsActive ()
void	LLSetDataToOld ()
	resets the "new data flag".
void	LLLockReceiveBuffer ()
	locks the receive buffer, i.e.
byte	LLReceiveBufferLocked ()
void	LLReleaseReceiveBuffer ()
	unlocks the receive buffer, i.e.
void	LLSetDataToNew ()
	sets the "new data flag".
byte	LLDataIsNew ()
byte	LLGetFieldStrength ()
void	LLSetFieldStrength (byte value)
	sets the field strength at which packets are sent out (0-255)
unsigned short	LLCalcCRC16 (byte header_data, byte payload_data, byte payload_size)
	calculates the crc-16 checksum over the rf packet (ll header + payload)
byte	LLSendPacket (byte slot_limit)
	prepares the LL header and instructs the rf layer to send the packet out (via flag).
byte	LLGetRemainingPayloadSpace ()
byte	LLSentPacketInThisSlot ()
ACL Layer Functions
void	ACLStartUp ()
	is the first function in any case, runs selftest and aclinit
void	ACLInit ()
	start ACL and lower layers, resets the whole stack
byte	ACLSubscribe (byte LL_type_h, byte LL_type_l)
	adds a type to the subscription list
byte	ACLUnsubscribe (byte LL_type_h, byte LL_type_l)
	deletes a type out of the subscription list
void	ACLFlushSubscriptions ()
	deletes all subscriptions (not the default ones)
void	ACLSubscribeAll ()
	subscribes to any possible type (all packets are received)
void	ACLAnswerOnACM ()
	if a control msg comes in that requires an answer, it is answered
void	ACLNoAnswerOnACM ()
	if a control msgs comes in that requires an answer, it will not be answered
byte	ACLSubscribeDefault ()
	subscribes to the default types (control msgs..)
byte	ACLVerifySubscription (byte type_h, byte type_l)
	checks if a subscription is there
byte	ACLProcessControlMessages ()
	internal: is called if control msg is there
void	ACLSetFieldStrength (byte power)
	sets the field strength of transmitter signals
byte	ACLSendingBusy ()
	returns true if LL has Packet in send queue
byte	ACLGetSendSuccess ()
	returns the result of last packet transmission.
byte	ACLMatchesMyIP (char *buffer, byte start)
	checks, if buffer holds my IP
byte	ACLSendPacket (byte slot_timeout)
	queues a packet for transmission
void	ACLAbortSending ()
	stops a running transmission
byte	ACLClearSendData ()
	deletes the send buffer of ACL
bool	ACLAddNewType (byte type_h, byte type_l)
	adds a new type tuple to the payload
byte	ACLAddData (byte newByte)
	adds one byte data into the ACL send buffer
byte	ACLGetRemainingPayloadSpace ()
	returns the number of free bytes in the transmit buffer
byte	ACLGetReceivedPayloadLength ()
	returns the number of payload bytes of the last packet received
signed char	ACLGetReceivedDataLength (byte type_h, byte type_l)
	searches the last received packet for the given type and returns the data length of the entry found.
char *	ACLGetReceivedData (byte type_h, byte type_l)
char	ACLGetReceivedByte (byte type_h, byte type_l, byte position)
	searches the first occurrence of type tuple and returns the position-th byte after that tuple
byte	ACLFoundReceivedType (byte type_h, byte type_l)
void	ACLSetControlMessagesBehaviour (boolean ignore, boolean pass)
	note that the settings are independent.
byte	ACLSentPacketInThisSlot ()
void	ACLStart ()
	restart ACL after ACLstop()
void	ACLStop ()
	stops the RF stack. Everything is hold, continues after ACLstart. msg stay in queue.
void	ACLLockReceiveBuffer ()
	locks the receive buffer: no new msgs are received
byte	ACLReceiveBufferLocked ()
void	ACLReleaseReceiveBuffer ()
	un-lock the receivebuffer;
void	ACLSetDataToOld ()
	set received data to "old": means ACLDataIsNew will not return true unless a new packet was received
void	ACLSetDataToNew ()
	set received data to "new": means ACLDataIsNew will return true until ACLSetDataToOld() is called
byte	ACLDataIsNew ()
byte	ACLDataReceivedInThisSlot ()
byte	ACLDataIsNewNow ()
	synonym for ACLDataReceivedInThisSlot()
byte	ACLAdressedDataIsNew ()
byte	ACLAdressedDataIsNewNow ()
byte	ACLSendPacketAdressed (nodeAddrType *address, byte timeout)
	sends out the current packet with a target ID
Received Packet Variables
An received data packet is copied into these variables once it arrived completely and and succeeded the crc test
xdata byte	LL_header_received [LL_HEADER_SIZE]
	last header received
xdata byte	LL_payload_received [LL_PAYLOAD_SIZE]
	last payload received
xdata byte	LL_payload_received_length
	length of last payload received
xdata byte	LL_tail_received [LL_TAIL_SIZE]
	last tail received
Packet Receive Buffer
During reception, an incoming packet is written to these variables and on complete arrival and successful crc test (if it is a data packet) is copied into the Received Packet variables. By this, the next packet can be received immediately.
volatile xdata byte	LL_header_receivebuffer [LL_HEADER_SIZE]
	temp store: header received
volatile xdata byte	LL_payload_receivebuffer [LL_PAYLOAD_SIZE]
	temp store: payload received
volatile xdata byte	LL_payload_receivebuffer_length
	temp store: of last payload received
volatile xdata byte	LL_tail_receivebuffer [LL_TAIL_SIZE]
	temp store: tail received
Variables For Next Packet to Send
The user and the ACL function write the payload of the next packet to send into these variables. No header and tail variables are needed for "send" because they are evaluated not until sending time.
xdata byte	LL_payload_send [LL_PAYLOAD_SIZE]
	next payload to send
xdata byte	LL_payload_send_length
	length of next payload to send
Packet To Send Buffer
On calling LLSendPacket(), the payload to send is copied into these send buffer variables. The LL_payload_send variable can be accessed again immediately. The "realtime" part only accesses these variables.
xdata byte	LL_header_sendbuffer [LL_HEADER_SIZE]
	temp store: header to send
xdata byte	LL_payload_sendbuffer [LL_PAYLOAD_SIZE]
	temp store: payload to send
xdata byte	LL_payload_sendbuffer_length
	temp store: length of payload to send
xdata byte	LL_tail_sendbuffer [LL_TAIL_SIZE]
	temp store: tail to send
statistical variables
xdata unsigned long	statsRfSlotsInSync
	for a master: number of slots not in short search for beacon, for slave: number of slots in sync. only in these slots data can be sent
xdata unsigned long	statsRfSlotsNeedToSend
	those of the statsRfSlotsInSync where the node had to send something
xdata unsigned long	statsRfArbitrationWon
	those of the statsRfSlotsNeedToSend where arbitration was won
xdata unsigned long	statsRfDataPacketsReceivedNotNeedingToSend
	those of the statsRfSlotsNoNeedToSend where the node didn't detect another arbitration signal
Functions
void	isr_timer0 ()
	the "realtime"-part of the software.
void	isr_timer2 ()
	this is a dummy isr.
void	main (void)
	the "application level" part of the software.