root / branches / wireless / code / lib / include / libwireless / wireless.h @ 1935
History | View | Annotate | Download (5.69 KB)
1 | 18 | bcoltin | /**
|
---|---|---|---|
2 | 1617 | dsschult | * Copyright (c) 2009 Colony Project
|
3 | *
|
||
4 | 242 | bcoltin | * 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 | 1617 | dsschult | *
|
13 | 242 | bcoltin | * The above copyright notice and this permission notice shall be
|
14 | * included in all copies or substantial portions of the Software.
|
||
15 | 1617 | dsschult | *
|
16 | 242 | bcoltin | * 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 | 18 | bcoltin | * @file wireless.h
|
28 | 1617 | dsschult | * @brief Contains definitions for using the wireless library
|
29 | 18 | bcoltin | *
|
30 | 1617 | dsschult | * Contains definitions for interfacing with the
|
31 | * wireless library.
|
||
32 | 18 | bcoltin | *
|
33 | 1617 | dsschult | * @author Colony Project, CMU Robotics Club
|
34 | 18 | bcoltin | **/
|
35 | 191 | bcoltin | |
36 | #ifndef WIRELESS_H
|
||
37 | #define WIRELESS_H
|
||
38 | 738 | bcoltin | |
39 | 1617 | dsschult | // need this for C99 int types
|
40 | #ifndef STDINT_H
|
||
41 | #define STDINT_H
|
||
42 | #include <stdint.h> |
||
43 | #endif
|
||
44 | 18 | bcoltin | |
45 | 1617 | dsschult | |
46 | 18 | bcoltin | /**
|
47 | * @defgroup wireless Wireless
|
||
48 | 1617 | dsschult | * @brief Interface with the wireless library
|
49 | 18 | bcoltin | *
|
50 | 1617 | dsschult | * Interface with the wireless library.
|
51 | 18 | bcoltin | *
|
52 | * @{
|
||
53 | **/
|
||
54 | 1617 | dsschult | |
55 | /**@defgroup wl_defines Public Constants
|
||
56 | * @{ **/
|
||
57 | |||
58 | /**@brief basic group code **/
|
||
59 | #define BASIC UINT8_C(0) |
||
60 | 18 | bcoltin | |
61 | 1617 | dsschult | /**@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 | 18 | bcoltin | /**
|
116 | * @struct PacketGroupHandler
|
||
117 | 738 | bcoltin | * A PacketGroupHandler represents a packet group, and is used to
|
118 | 18 | bcoltin | * register a packet group with the wireless library. It contains
|
119 | 1617 | dsschult | * a function pointer to the packet handler function and the priority
|
120 | * of the packet group.
|
||
121 | 18 | bcoltin | **/
|
122 | 1617 | dsschult | typedef struct { |
123 | |||
124 | // function pointer of handler for this packet group
|
||
125 | FNPTR; |
||
126 | 18 | bcoltin | |
127 | 1617 | dsschult | // priority for this packet group
|
128 | uint8_t priority; |
||
129 | |||
130 | } PacketGroupHandler; |
||
131 | 738 | bcoltin | |
132 | |||
133 | 1617 | dsschult | /**@defgroup wl_functions Public API Functions
|
134 | * @{ **/
|
||
135 | |||
136 | // the init function
|
||
137 | 738 | bcoltin | |
138 | 1617 | dsschult | /**@brief Initialize wireless. **/
|
139 | int8_t wl_init(void);
|
||
140 | 738 | bcoltin | |
141 | 1617 | dsschult | /**@brief Terminate wireless. **/
|
142 | int8_t wl_terminate(void);
|
||
143 | 18 | bcoltin | |
144 | 60 | bcoltin | |
145 | 1617 | dsschult | // the send functions
|
146 | 60 | bcoltin | |
147 | 1617 | dsschult | /**@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 | 18 | bcoltin | |
150 | 1617 | dsschult | /**@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 | 18 | bcoltin | |
153 | 1617 | dsschult | /**@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 | 191 | bcoltin | #endif |