The Particle computer is generally to be used with the AwareCon protocol stack. The AwareCon protocol stack is a synchronized protocol. This means, it has to fulfil some lower level network task in a periodic manner. For that, Timer1 and Timer2 are used to take care of timing and flow of the protocol. If the AwareCon protocol is running (e.g. like through ACLStartup() or ACLStart() ) the microprocessor is interrupted periodically for the RF stack.
This means, any
program on the Particle is interrupted every 13 ms for the participation in the
network like synchronization, data traffic etc.
Make sure that your
program is able to handle interruptions. This can be crucial e.g. for A/D
your program in the time-slotted way. E.g. wait for the next application time
or find out how much time is left for your application until the next interrupt
will occur with function like
RF500usLeft() // returns 1 (true) if 100,200,500 us are left
We recommend to always
built your software on example programs to avoid mistakes.
All example programs can be found in the Software site under Example programs.
As an introduction, we take a look at the easiest program of our examples, the beacon. The beacon example sends out a packet every second with some void data. The program has a beacon.c and beacon.h file. Download the beacon files and program your particle with it.
We start with the beacon.h file:
// headerfile for application
#define byte BYTE
#define boolean BOOLEAN
#define true TRUE
#define false FALSE
#define global GLOBAL
// all defines until now are just general necessary for the code of the stack etc.
#include "system\acltypes.h" // the acl types // this file includes the know acl types
// this file includes defines like addresses for the processor
// this file includes all names of registers of the processor
// this file includes necessary definition of the Particle Computer version 2.02
// this file includes the functions like A/D serial and so on of the processor
// this file provides i2c for the particle internals
// interface to the external 32k EEPROM
// functions of the board like selfttest..
#include "system\awarecon#082.c" // stack
// the stack from RF layer to ACL
// over the air programming (needs the EEPROM)
// configurations bits of the processor - see Microchips datasheet for the PIC
This is the minimal header file to use a particle in its basic configuration. It includes all necessary files and functions. The next file to look at is the application file. The beacon.c:
// own pins and stuff
// this function is called from the fsm at the end of an rf slot
// make sure that it terminates in time
this first function needs
some explanation. It’s a call back function from the AwareCon Stack. It is
called at the end of each slot to run tasks that need to be proceeded every slot.
It is processed within the interrupt function of the RF protocol. You can place
code in there and it will be executed each slot. Don’t use endless loops and
Make sure that any code placed in SlotEndCallBack() terminates before the 13ms are over! We generally do not recommend to use this function at all. Better leave it blank. This is for experts!
If you are not sure how long your code will need to execute, never place it in the SlotEndCallBack(). If you want to have code that is executed every slot, there are other possibilities like having an endless loop and wait one slot before the next round starts. The later “streamer.c” example shows to do it. We take a look at the main function of the beacon.c program:
DelayMs(1000); // wait one second
if (!ACLSendingBusy()) // check whether the send buffer is free#
ACLAddNewType(102,102); //place a new type in the ACL buffer
ACLAddData(1); // add some useless data
// place the next type in ACL
ACLAddData(99); // add some data
ACLSendPacket(20); // send out the packet within the next 20 slots or cancel it
After the initialization,
the endless loop always starts with waiting one second, checks if the ACL buffer
is free and then prepares a packet and then sends it out.
To better understand the communication in the AwareCon, here are some of the most important functions:
ACLAddNewType(int type_h, int type_l);
int ACLAddData(int data);
int ACLSendPacket(int slot_timeout);
// return the number of bytes free in the
// return the number of bytes free in the current packet
int ACLSubscribe(byte LL_type_h,LL_type_l);
int ACLUnsubscribe(byte LL_type_h,LL_type_l);
int ACLFoundReceivedType(int type_h, int type_l);
char* ACLGetReceivedData(int type_h, int type_l);
The next example, the repeater, should demonstrate how reception of data is done. Prepare another Particle with the repeater code and turn repeater and beacon on together. Each time, the beacon sends out a packet, the repeater will receive it and repeat parts from the data. You can watch this on your ParticleAnalyzer with your Xbridge.
The line ACLSubscribe(102,102); causes the Stack to receive data packets that contain the 102,102=”ABC” Artefact Data Type as the first type. AppSetLEDBehaviour(LEDS_ON_RECEIVE); uses the LEDs on the Particle in a special mode: the red LED runs like always (slow flickering if not synchronized, fast if in sync), but the blue LED doesn’t show a RF link like before but flashes on a received packet.
The line while (!ACLDataIsNew()); waits for a new packet to come in. A new packet in this context means, it has to carry a subscribed artefact type; in this case only the 102,102. Then the repeater reads out the received data and repeats it in its own packet led by a 255.
The ACLSetDataToOld(); is necessary as is sets the “new” flag of the received packet back to “old”. This means the next ACLDataIsNew() will return false until a really new packet came in from RF.
The last example is the streamer. It demonstrate how to write and application that processes some action every 13 ms slots without using the slot end call back function. [to be done]