Statistics
| Revision:

root / branches / wireless / code / lib / include / libwireless / wireless.h @ 1935

History | View | Annotate | Download (5.69 KB)

1
/**
2
 * Copyright (c) 2009 Colony Project
3
 * 
4
 * Permission is hereby granted, free of charge, to any person
5
 * obtaining a copy of this software and associated documentation
6
 * files (the "Software"), to deal in the Software without
7
 * restriction, including without limitation the rights to use,
8
 * copy, modify, merge, publish, distribute, sublicense, and/or sell
9
 * copies of the Software, and to permit persons to whom the
10
 * Software is furnished to do so, subject to the following
11
 * conditions:
12
 * 
13
 * The above copyright notice and this permission notice shall be
14
 * included in all copies or substantial portions of the Software.
15
 * 
16
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
18
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
20
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
21
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
23
 * OTHER DEALINGS IN THE SOFTWARE.
24
 **/
25

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

    
36
#ifndef WIRELESS_H
37
#define WIRELESS_H
38

    
39
// need this for C99 int types
40
#ifndef STDINT_H
41
#define STDINT_H
42
#include <stdint.h>
43
#endif
44

    
45

    
46
/**
47
 * @defgroup wireless Wireless
48
 * @brief Interface with the wireless library
49
 *
50
 * Interface with the wireless library.
51
 *
52
 * @{
53
 **/
54
 
55
/**@defgroup wl_defines Public Constants
56
 * @{ **/
57
 
58
/**@brief basic group code **/
59
#define BASIC UINT8_C(0)
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

    
115
/**
116
 * @struct PacketGroupHandler
117
 * A PacketGroupHandler represents a packet group, and is used to
118
 * register a packet group with the wireless library. It contains
119
 * a function pointer to the packet handler function and the priority
120
 * of the packet group.
121
 **/
122
typedef struct {
123
    
124
    // function pointer of handler for this packet group
125
    FNPTR;
126

    
127
    // priority for this packet group
128
    uint8_t priority;
129
    
130
} PacketGroupHandler;
131

    
132

    
133
/**@defgroup wl_functions Public API Functions 
134
 * @{ **/
135
 
136
// the init function
137

    
138
/**@brief Initialize wireless. **/
139
int8_t wl_init(void);
140

    
141
/**@brief Terminate wireless. **/
142
int8_t wl_terminate(void);
143

    
144

    
145
// the send functions
146

    
147
/**@brief The core send function. This will take all possible arguments and send all types of packets. **/
148
int16_t wl_send(uint8_t *data, uint8_t length, uint8_t group, uint8_t scope, uint16_t dest, uint8_t mode);
149

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

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

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

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

    
162

    
163
// the ack function
164

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

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

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

    
174

    
175
// the receive functions
176

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

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

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

    
186

    
187
// the group register function
188

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

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

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

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

    
199
#endif