THE PARTICLE COMPUTER DOCU
                    (program the particle computer)                   

 

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 measurements.Think for your program in the time-slotted way. E.g. wait for the next application time with RFDelaySlots(1) or find out how much time is left for your application until the next interrupt will occur with function like 

long RFMicroSecondsUntilNextSlot()         // returns the us left in the actual slot until next interrupt
RF100usLeft
()  
RF200usLeft
()  
RF500usLeft
()                              // returns 1 (true) if 100,200,500 us are left

General look of a program on the particle computer- 
3 Introduction examples (beacon, streamer, repeater)

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
#case 
#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
#include "boards\18f6720.h"
// this file includes defines like addresses for the processor
#include "boards\18f6720_R.h"
// this file includes all names of registers of the processor
#include "boards\pc202.h"
// this file includes necessary definition of the Particle Computer version 2.02
#include "boards\18f6620.c"
// this file includes the functions like A/D serial and so on of the processor
#include "boards\pci2c.c"
// this file provides i2c for the particle internals
#include "boards\pceeprom.c"
// interface to the external 32k EEPROM
#include "boards\pc202.c"
// functions of the board like selfttest..
#include "system\awarecon#082.c" // stack
// the stack from RF layer to ACL
#include "system\otap.c"
// over the air programming (needs the EEPROM)
#fuses hs,noprotect,nobrownout,nolvp,put,nowdt
// 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:

#include "beacon.h"      // 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

#separate
void SlotEndCallBack()  

{  
}

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 such there!

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:

 

void main()
{
    PCInit();

    ACLInit();
    enable_interrupts(global);    

    while (1)
    {

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
    
ACLAddData(2); 
    
ACLAddData(3); 
    
ACLAddNewType(ACL_TYPE_STE_HI,ACL_TYPE_STE_LO);  // 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:

 

  1. Preparing and Transmitting Packets

         int ACLAddNewType(int type_h, int type_l); // places a new type in the current packet  

        int ACLAddData(int data);             // appends data to the last type

        int ACLSendPacket(int slot_timeout);        // sends out the current packet

        int ACLGetRemainingPayloadSpace();         // return the number of bytes free in the current packet

  1. Status and flow control

      int ACLSendingBusy();                 //returns 1 (true) if the transmit buffer is still waiting to be sent

       int ACLGetSendSuccess();              // return true if last transmission was ok

  1. Subscribing to ACL Types

         int ACLSubscribe(byte LL_type_h,LL_type_l); 

      int ACLUnsubscribe(byte LL_type_h,LL_type_l);

     

  1. Receiving Data

         int ACLDataIsNew();                                //returns 1 (true) if data was received since last  ACLSetDataToOld();

     int ACLFoundReceivedType(int type_h, int type_l);    // returns 1 (true) if given type was in the last received packet

     char* ACLGetReceivedData(int type_h, int type_l);   // returns pointer to the data of the given type, if found

   

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]