Project

General

Profile

Revision 1617

wl: clean up unit tests

View differences:

wireless.h
1 1
/**
2
 * Copyright (c) 2007 Colony Project
3
 *
2
 * Copyright (c) 2009 Colony Project
3
 * 
4 4
 * Permission is hereby granted, free of charge, to any person
5 5
 * obtaining a copy of this software and associated documentation
6 6
 * files (the "Software"), to deal in the Software without
......
9 9
 * copies of the Software, and to permit persons to whom the
10 10
 * Software is furnished to do so, subject to the following
11 11
 * conditions:
12
 *
12
 * 
13 13
 * The above copyright notice and this permission notice shall be
14 14
 * included in all copies or substantial portions of the Software.
15
 *
15
 * 
16 16
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17 17
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
18 18
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
......
25 25

  
26 26
/**
27 27
 * @file wireless.h
28
 * @brief Contains definitions for the wireless library.
28
 * @brief Contains definitions for using the wireless library
29 29
 *
30
 * Contains functions for the wireless library.
30
 * Contains definitions for interfacing with the 
31
 * wireless library.
31 32
 *
32
 * @author Brian Coltin, Colony Project, CMU Robotics Club
33
 * @author Colony Project, CMU Robotics Club
33 34
 **/
34 35

  
35 36
#ifndef WIRELESS_H
36 37
#define WIRELESS_H
37 38

  
38
//Note: If this is raised above 16, we will need to do
39
//something about frame numbers for TX Status packets.
40
/**
41
 * The maximum number of packet groups.
42
 **/
43
//TODO: a PacketGroupHandler is at least 10 bytes (I don't know if function pointers are 2 bytes
44
// or 4 bytes).  That means that in the c file, your array of packet groups is at least 160 bytes.
45
// Normally that might be fine (the robot's avr chips have 4k SRAM), but austin's chip only has
46
// 1k SRAM, so if this number can be reduced or if the size of the struct could be reduced, that would be a plus.
47
#define WL_MAX_PACKET_GROUPS 16
39
// need this for C99 int types
40
#ifndef STDINT_H
41
#define STDINT_H
42
#include <stdint.h>
43
#endif
48 44

  
45

  
49 46
/**
50 47
 * @defgroup wireless Wireless
51
 * @brief Wireless definitions.
48
 * @brief Interface with the wireless library
52 49
 *
53
 * Contains functions and definitions for dealing with wireless functionality.<br><br>
50
 * Interface with the wireless library.
54 51
 *
55
 * The wireless library provides a modular method for dealing with
56
 * wireless packets, by allowing packet groups to be registered.
57
 * A packet group is a collection of packets which share a packet
58
 * group code. Each packet in the group also has a type. A packet
59
 * group code and type are sent with each packet. When a packet
60
 * with a group code registered in the wireless library is
61
 * received, the corresponding event handler is called. The
62
 * event handler uses the packet type and other information
63
 * stored in the packet to respond.<br><br>
64
 *
65
 * This architecture allows different wireless functionality to be
66
 * defined and handled separately, making it simpler and more
67
 * efficient to take advantage of the XBee's wireless functionality.
68
 *
69 52
 * @{
70 53
 **/
54
 
55
/**@defgroup wl_defines Public Constants
56
 * @{ **/
57
 
58
/**@brief basic group code **/
59
#define BASIC UINT8_C(0)
71 60

  
61
/**@brief global scope **/
62
#define GLOBAL UINT8_C(0)
63

  
64
/**@brief local pan scope **/
65
#define PAN UINT8_C(1)
66

  
67
/**@brief broadcast address **/
68
#define BROADCAST UINT16_C(0xFFFF)
69

  
70
/**@brief reliable (TCP) mode **/
71
#define RELIABLE UINT8_C(0)
72

  
73
/**@brief fast (UDP) mode **/
74
#define FAST UINT8_C(1)
75

  
76
/**@brief standard priority **/
77
#define NORMAL_PRIORITY UINT8_C(0)
78

  
79
/**@brief high priority, handle immediately **/
80
#define HIGH_PRIORITY UINT8_C(1)
81

  
82
/**@brief packet still in sending phase **/
83
#define SENDING UINT8_C(0)
84

  
85
/**@brief packet was send successfully **/
86
#define ACK_OK UINT8_C(1)
87

  
88
/**@brief packet failure - no acknowledgment **/
89
#define ACK_FAILURE UINT8_C(2)
90

  
91
/**@brief packet failure - network too busy **/
92
#define CCA_FAILURE UINT8_C(3)
93

  
94
/**@brief packet handler function pointer type **/
95
#define FUNC func
96

  
97
/**@brief packet handler function pointer type **/
98
#define FNPTR void (*FUNC)(uint8_t* data,uint8_t length,uint8_t source)
99

  
100
// TODO: this max may be too big b/c the packet handler array stores 3*MAX_PACKET_GROUPS bytes 
101
/**@brief maximum number of packet groups, size of handler array **/
102
#define MAX_PACKET_GROUPS UINT8_C(16)
103

  
104
/**@brief init_flag when library has not been initialized **/
105
#define INIT_NO UINT8_C(0)
106

  
107
/**@brief init_flag when library has been initialized **/
108
#define INIT_YES UINT8_C(1)
109

  
110
/**@brief numer of reliable sending retries **/
111
#define NUM_RETRIES UINT8_C(3)
112

  
113
/**@} **/ // end defines group
114

  
72 115
/**
73 116
 * @struct PacketGroupHandler
74 117
 * A PacketGroupHandler represents a packet group, and is used to
75 118
 * register a packet group with the wireless library. It contains
76
 * handlers for various events which can occur related to a packet
77
 * group.
119
 * a function pointer to the packet handler function and the priority
120
 * of the packet group.
78 121
 **/
79
//TODO: the order of member variables in this struct should be changed in case the compile packs the struct
80
// In order to achieve the best packing, the variables should be listed in order of decreasing memory size.
81
// Thus, pointers should be first, followed by int, followed by char.
82
typedef struct
83
{
84
	/**
85
	 * The group code for this packet group. This number
86
	 * must be unique. The maximum number of packet groups
87
	 * is defined by WL_MAX_PACKET_GROUPS.
88
	 **/
89
  //TODO: if this number must be less than or equal to WL_MAX_PACKET_GROUPS, don't you only need
90
  // one byte for it and it can be made an unsigned char?
91
	unsigned int groupCode;
122
typedef struct {
123
    
124
    // function pointer of handler for this packet group
125
    FNPTR;
92 126

  
93
	/**
94
	 * Called every half second (not in interrupt,
95
	 * but in wl_do).
96
	 **/
97
	void (*timeout_handler) (void);
127
    // priority for this packet group
128
    uint8_t priority;
129
    
130
} PacketGroupHandler;
98 131

  
99
	/**
100
	 * Called when a transmit status packet is received
101
	 * from the XBee where the first four bits of the frame
102
	 * are  the group code.
103
	 *
104
	 * @param frame the last four bits of the frame
105
	 * @param received is true if we received an ack, 0 if
106
	 * we did not.
107
	 **/
108
	void (*handle_response) (int frame, int received);
132
static PacketGroupHandler wl_packet_handlers[MAX_PACKET_GROUPS];
109 133

  
110
	/**
111
	 * Called when we receive a packet from this group.
112
	 *
113
	 * @param type the packet type
114
	 * @param source the 16-bit address of the XBee this
115
	 * packet was sent from
116
	 * @param packet the packet received
117
	 * @param length the length of the packet
118
	 **/
119
	void (*handle_receive) (char type, int source, unsigned char* packet, int length);
134
/**@defgroup wl_functions Public API Functions 
135
 * @{ **/
136
 
137
// the init function
120 138

  
121
	/**
122
	 * Called for any cleanup when the network is turned off.
123
	 **/
124
	void (*unregister) (void);
139
/**@brief Initialize wireless. **/
140
int8_t wl_init(void);
125 141

  
126
} PacketGroupHandler;
142
/**@brief Terminate wireless. **/
143
int8_t wl_terminate(void);
127 144

  
128
/**@brief Initialize the wireless library **/
129
int wl_init(void);
130
/**@brief Uninitialize the wireless library **/
131
void wl_terminate(void);
132
/**@brief Perform wireless library functionality **/
133
void wl_do(void);
134
/**@brief Register a packet group with the wireless library **/
135
void wl_register_packet_group(PacketGroupHandler* h);
136
/**@brief Unregister a packet group with the wireless library **/
137
void wl_unregister_packet_group(PacketGroupHandler* h);
138 145

  
139
/**@brief Send a packet to a specific robot in any PAN **/
140
int wl_send_robot_to_robot_global_packet(char group, char type, char* data, int len, int dest, char frame);
141
/**@brief Send a packet to a specific robot in our PAN **/
142
int wl_send_robot_to_robot_packet(char group, char type, char* data, int len, int dest, char frame);
143
/**@brief Send a packet to all robots **/
144
int wl_send_global_packet(char group, char type, char* data, int len, char frame);
145
/**@brief Send a packet to all robots in our PAN **/
146
void wl_send_pan_packet(char group, char type, char* data, int len, char frame);
146
// the send functions
147 147

  
148
/**@brief Set the PAN we are using **/
149
int wl_set_pan(int pan);
150
/**@brief Get the PAN we are using **/
151
int wl_get_pan(void);
152
/**@brief Set the channel we are using **/
153
int wl_set_channel(int channel);
154
/**@brief Get the channel we are using **/
155
int wl_get_channel(void);
156
/**@brief Get the 16-bit address of the XBee module **/
157
int wl_get_xbee_id(void);
158
/**@brief Set the com port on a computer, undefined on the robot.**/
159
void wl_set_com_port(char* port);
148
/**@brief The core send function. This will take all possible arguments and send all types of packets. **/
149
int16_t wl_send(uint8_t *data, uint8_t length, uint8_t group, uint8_t scope, uint16_t dest, uint8_t mode);
160 150

  
161
/** @} **/ // end defgroup
151
/**@brief Wrapper for core send function that will send a global packet across the current channel. **/
152
int16_t wl_send_global(uint8_t *data, uint8_t length, uint8_t group);
162 153

  
154
/**@brief Wrapper for core send function that will send a packet across the current channel on the current pan. **/
155
int16_t wl_send_pan(uint8_t *data, uint8_t length, uint8_t group);
156

  
157
/**@brief Wrapper for core send function that will send a packet across the current channel to a specific robot. **/
158
int16_t wl_send_robot(uint8_t *data, uint8_t length, uint8_t group, uint16_t dest, uint8_t mode);
159

  
160
/**@brief Default (i.e. basic) send wrapper. **/
161
int16_t wl_send_basic(uint8_t *data, uint8_t length);
162

  
163

  
164
// the ack function
165

  
166
/**@brief Returns the number of acknowledgment errors. **/
167
uint8_t wl_ack_error(void);
168

  
169
/**@brief Checks a specific packet for the acknowledgement status. **/
170
int8_t wl_ack_check(uint8_t packet);
171

  
172
/**@brief Resets acknowledgement statistics back to zero. **/
173
void wl_ack_reset(void);
174

  
175

  
176
// the receive functions
177

  
178
/**@brief The main receive function.  Dispatches packets for registered handlers and returns next basic packet if available. **/
179
int8_t wl_get(char *data, uint8_t length);
180

  
181
/**@brief Returns the next basic packet if available. **/
182
int8_t wl_get_basic(char *data, uint8_t length);
183

  
184
/**@brief Dispatches packets for registered handlers. **/
185
int8_t wl_dispatch(void);
186

  
187

  
188
// the group register function
189

  
190
/**@brief Function to register new packet handlers (for non-default groups only). **/
191
int8_t wl_register_handler(uint8_t group, FNPTR, uint8_t priority);
192

  
193
/**@brief Function to unregister existing packet handlers (for non-default groups only). **/
194
int8_t wl_unregister_handler(uint8_t group);
195

  
196
/**@} **/ //end functions group
197

  
198
/**@} **/ //end wireless group
199

  
163 200
#endif
164

  

Also available in: Unified diff