THE PARTICLE COMPUTER DOCU
                    (The AwareCon Functions Reference)                   

This chapter summarises and explains the function that the AwareCon provides to the programmer. They are grouped together for the according semantic context.


Subscriptions

 

int ACLSubscribe(byte LL_type_h,LL_type_l);

 

Adds a type to the subscription list. The list contains a maximum of 8 different (Artefact) types to subscribe to. One is reserved (“ACM”) for network controls. All packets that are on the RF channel are being scanned for the first type which is normally interpreted as the Artefact type. If this first type of a packet is found the local subscription list, the packet is received and the “new” flag (see ACLDataIsNew()) is set.

 

void ACLSubscribeAll();

 

All incoming packets are being received. The subscription list is ignored.

 

int ACLUnsubscribe(byte LL_type_h,LL_type_l);

 

The given type is deleted from the subscription list and the corresponding packets are no more received. If the type is not found nothing happens.

 

int ACLFlushSubscriptions();

 

Deletes all subscription except the “ACM” in the subscription list.

     

int ACLVerifySubscription(int type_h,int type_l);         

 

Returns 1 if the given type is found in the subscription list.


Transmission

 

 

int ACLAddNewType(int type_h, int type_l);

 

Adds the given type into the ACL send buffer. The then following data is considered to belong to this type

Return values:

            0: Type was successfully placed in the transmit buffer

            1: Error: Not enough space left in the transmit buffer

            2: Error: ACL buffer lock active

 

int ACLAddData(int data);   

 

Adds the given byte into the ACL transmit buffer. It belongs to the last type that had been placed in the transmit buffer.

Return values:

            0: Data was successfully placed in the transmit buffer

            1: error: Not enough space left in the transmit buffer

            2: Error: ACL buffer lock active

 

int ACLSendPacket(int slot_timeout);

 

Starts a packet transmission. The Acl transmit buffer is moved to the next layer if possible. During the next slot_timeout slots, the LL layer tries to send the packet out. If after that number of RF slots the packet is still not sent, it is deleted.

Return values:

            1: Packet successfully enqueued in LL layer

            0: error enqueing the packet

(probably the LL layer still has a packet in the queue)

     

 

void ACLAbortSending();

 

If a packet was in the transmission queue, it is deleted. All data placed in the ACL buffer is deleted. ACL and LL are reset and ready for the next data.

 

int ACLClearSendData();     

                                  

The data placed in the ACL buffer is deleted if possible (no locks active). ACL is reset and ready to proceed. The packets enqueued for transmission are not touched.

 

int ACLGetRemainingPayloadSpace();

 

Returns the number of free bytes in the ACL transmit buffer. Total is 64 bytes.

 

int ACLSendingBusy();

 

Returns true if LL has Packet in transmit queue.

 

int ACLGetSendSuccess();

Returns 1 if last packet was send out and no error occurred. All other cases returns 0.

 

 

int ACLSentPacketInThisSlot();

 

Returns 1 if a data packet has been send in “this slot”. “This slot” means in this context the rf slot that just been proceeded. If a transmission was more than one slot ago (more than 13ms) then this function would return 0. In all other cases returns 0.

 


Reception of Data

 

 

 

int ACLGetReceivedPayloadLength();

 

Returns the number of bytes in the Receive buffer.

 

signed int ACLGetReceivedDataLength(int type_h, int type_l);

 

Return the number of data bytes in the receive buffer that belong to the given type. Returns 0 if the given type was found, but doesn’t carry and additional data.Return –1 if the given type was not found.

 

 

char* ACLGetReceivedData(int type_h, int type_l);   

 

Returns a pointer into the receive buffer to the first data element corresponding to the given type.

Attention: use this function only if you are sure that the given type is found in the receive buffer and that the corresponding number of data is at least one! Otherwise the return pointer position will be undefined!! 

 

 

char ACLGetReceivedByte(int type_h, int type_l, int position);  

 

Returns one byte of the payload from the receive buffer of the given type.

Attention: use this function only if you are sure that the given type is found in the receive buffer and that the corresponding number of data is at least one! Otherwise the return will be undefined!!

 

 

 


Reception Control

 

int ACLDataIsNew();    

 

Returns 1 if data in receive buffer is "new", else 0. A “new” data means that the data has been received recently and the flag for this data packet has not been set to old yet. Data to be received must match to the subscriptions in the subscriptions list!!

 

int ACLDataIsNewNow(); 

 

Returns 1 if data in receive buffer is "new", else 0. A “new” data here means that the data has been received in the last slot and that the flag for this data packet has not been set to old yet. Data to be received must match to the subscriptions in the subscriptions list!! If the reception of the last packet is more than one RF slot ago (more than 13ms), the functions returns 0.

 

void ACLSetDataToOld();

 

The data in the the receive buffer is flagged as “old”. From this point on , the ACLDataIsNew() will return 0 until a new packet was received from the RF channel.

 

void ACLLockReceiveBuffer();

 

Locks the receive buffer. Incoming packets from RF will not be received until release of the buffer. Use this function if you need long time to process the received buffer and don’t want to make a copy of the whole buffer.

 

int ACLReceiveBufferLocked();

 

Returns 1 if receive buffer is locked else 0.

 

void ACLReleaseReceiveBuffer();

 

Un-locks the receivebuffer. Flags the Data in the receive buffer as “old”. Incoming Data is received (if subscribed to) and the flags are set accordingly.

 

 

int ACLFoundReceivedType(int type_h, int type_l);

     

Returns 1 of the given type is found in the receive buffer. Else returns 0.

 

 

 

 

 


 

Addressed Traffic

 

The address information is represented by the CAD type plus 8 bytes of the target ID. This consumes 11 bytes in the ACL buffer. (2 bytes type + 1 byte length + 8 byte ID). This type just has to be placed within a packet to make the packet an addressed one. Attention: If you prepare a packet to be sent to a certain target, the subscription mechanism will still be active and important. If the first data type (artefact type) is not in the subscription list of the receiver, the packet will not be received by the receiver even though the address is correct. Besides, all other active nodes that have subscription on the type will receive the packet as well even though it wasn’t meant for them.

Addressed traffic in the AwareCon is only the special use of the “CAD” type within the packet. It makes addressed traffic possible but doesn’t behave like the known addressed traffic in e.g. the internet, doesn’t cover any routing, filtering or security issues. The reception is still based on the subscriptions.

 

int ACLAdressedDataIsNew(); 

 

Builds on ACLDataIsNew(). It reacts the same but only returns 1 if the packets was addressed to the receiver. This means a CAD type plus 8 data bytes of the receiver ID was found in the packet.

 

int ACLAdressedDataIsNewNow();

 

combines the functionality of ACLAdressedDataIsNew() and ACLDataIsNewNow(). Only returns one if data was received in the current slot and was addressed to the receiver.

 

int ACLSendPacketAdressed(unsigned int add1, add2, add3, add4, add5, add6, add7, add8, timeout );

 

Starts a packet transmission addressed to the given 8 byte address. Make sure you have 11 bytes free in the ACL buffer to add the address information. The address information is represented

 

. The Acl transmit buffer is moved to the next layer if possible. During the next slot_timeout slots, the LL layer tries to send the packet out. If after that number of RF slots the packet is still not sent, it is deleted.

Return values:

            1: Packet successfully enqueued in LL layer

0: error enqueing the packet
(probably the LL layer still has a packet in the queue or not enough space)

 

 

 


Other AwareCon Tools and Controls

 

#separate
void AppRfSlotEndCallBack();

 

This function is a callback function called from the AwareCon Stack at the end of all protocol activities in each slot. All code placed here must be terminated before the next interrupt on timer1 (the RF interrupt) occurs. Code placed here will be executed once in each of the RF slots (every 13 ms). Don’t place any code in there if you don’t exactly know what you’re doing. Messy code can harm the protocol and therefore the stability of your whole setting!

 

 

void ACLSetFieldStrength(int power);

 

Sets the field strength of the transmitted signals. Valid parameters for power are 0..32 with 0 beeing the minimum transmit power. Turning the transmission power down reduces the range where possible receivers can receive the transmitted packets.Minimum transmit power corresponds to 0.01mW (<1m data transmission); maximum to 1mW (>100m outdoors, >10m office). The steps are nearly linear.

 

 

void AppSetLEDBehaviour(int ledstyle);  

 

The two LEDs on the Particle (red and blue) are normally controlled by the AwareCon. If the blue LED is on, the particle is synchronized to one or more partners. If the red LED is not blinking, the stack doesn’t run. If the red LED blinks fast, the particle is synchronized, if is blinks slower, the particle lost synchronization and looks for partners.

For convenience, the LEDs can show other things as well. Call this function with the following parameters:

  1. LEDS_NORMAL:

LED behave like described above

  1. LEDS_OFF

LED are not touched by the stack, the user can use them for anything

  1. LEDS_ON_SEND

The red LED behaves like described above, the blue LED flashes if a packet was sent out

  1. LEDS_ON_RECEIVE

The red LED behaves like described above, the blue LED flashes if a packet was received

  1. LEDS_ONLY_ONE

The red LED behaves like described above, the blue LED is free for the user’s control

  1. LEDS_ON_CRC_ERROR

The red Led flashes if a received packet had a CRC error,
the blue LED flashes if a good packet was received

 

 

 

void ACLInit();  

                                              

This function initialises all layers of the stack. This includes

 

 

void ACLStart(); 

     

Restarts the stack after a ACLStop(). Does not include the actions from ACLInit.

 

 

void ACLStop();

 

Freezes the AwareCon Stack. Packets in the queue are deleted. The ACL transmit buffer is not touched. Receive buffer is not touched. All states are preserved until the ACLStart() is called again.

Use those two function if you don’t need the RF stack running but you want to have the complete computer power from the PIC. After ACLStop(), the timer1 interrupt is disabled. Interruption will no more occur.