root / branches / wireless / code / projects / libwireless / wireless.h @ 1598
History | View | Annotate | Download (5.59 KB)
1 | 1576 | dsschult | /**
|
---|---|---|---|
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 | 1581 | dsschult | /**@defgroup wl_defines Public Constants
|
56 | * @{ **/
|
||
57 | 1588 | dsschult | |
58 | /**@brief basic group code **/
|
||
59 | #define BASIC UINT8_C(0) |
||
60 | 1576 | dsschult | |
61 | 1581 | 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 | 1587 | dsschult | /**@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 | 1590 | dsschult | /**@brief packet handler function pointer type **/
|
95 | 1598 | cmar | #define FUNC func
|
96 | 1590 | dsschult | |
97 | 1598 | cmar | /**@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(255) |
||
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 | 1581 | dsschult | /**@} **/ // end defines group |
111 | |||
112 | 1598 | cmar | /**
|
113 | * @struct PacketGroupHandler
|
||
114 | * A PacketGroupHandler represents a packet group, and is used to
|
||
115 | * register a packet group with the wireless library. It contains
|
||
116 | * a function pointer to the packet handler function and the priority
|
||
117 | * of the packet group.
|
||
118 | **/
|
||
119 | typedef struct { |
||
120 | |||
121 | // function pointer of handler for this packet group
|
||
122 | FNPTR; |
||
123 | 1581 | dsschult | |
124 | 1598 | cmar | // priority for this packet group
|
125 | uint8_t priority; |
||
126 | |||
127 | } PacketGroupHandler; |
||
128 | |||
129 | |||
130 | 1581 | dsschult | /**@defgroup wl_functions Public API Functions
|
131 | * @{ **/
|
||
132 | |||
133 | 1576 | dsschult | // the init function
|
134 | 1577 | dsschult | |
135 | /**@brief Initialize wireless. **/
|
||
136 | 1576 | dsschult | int8_t wl_init(void);
|
137 | |||
138 | 1577 | dsschult | /**@brief Terminate wireless. **/
|
139 | int8_t wl_terminate(void);
|
||
140 | |||
141 | |||
142 | 1576 | dsschult | // the send functions
|
143 | 1577 | dsschult | |
144 | /**@brief The core send function. This will take all possible arguments and send all types of packets. **/
|
||
145 | 1576 | dsschult | int8_t wl_send(char *data, uint8_t length, uint8_t group, uint8_t scope, uint8_t dest, uint8_t mode);
|
146 | 1577 | dsschult | |
147 | /**@brief Wrapper for core send function that will send a global packet across the current channel. **/
|
||
148 | 1576 | dsschult | int8_t wl_send_global(char *data, uint8_t length, uint8_t group);
|
149 | 1577 | dsschult | |
150 | /**@brief Wrapper for core send function that will send a packet across the current channel on the current pan. **/
|
||
151 | 1576 | dsschult | int8_t wl_send_pan(char *data, uint8_t length, uint8_t group);
|
152 | 1577 | dsschult | |
153 | /**@brief Wrapper for core send function that will send a packet across the current channel to a specific robot. **/
|
||
154 | 1578 | dsschult | int8_t wl_send_robot(char *data, uint8_t length, uint8_t group, uint8_t dest, uint8_t mode);
|
155 | 1576 | dsschult | |
156 | 1577 | dsschult | /**@brief Default (i.e. basic) send wrapper. **/
|
157 | int8_t wl_send_basic(char *data, uint8_t length);
|
||
158 | |||
159 | |||
160 | 1576 | dsschult | // the ack function
|
161 | 1577 | dsschult | |
162 | 1581 | dsschult | /**@brief Returns the number of acknowledgment errors. **/
|
163 | 1587 | dsschult | uint8_t wl_ack_error(void);
|
164 | 1576 | dsschult | |
165 | 1581 | dsschult | /**@brief Checks a specific packet for the acknowledgement status. **/
|
166 | int8_t wl_ack_check(uint8_t packet); |
||
167 | 1577 | dsschult | |
168 | 1581 | dsschult | /**@brief Resets acknowledgement statistics back to zero. **/
|
169 | void wl_ack_reset(void); |
||
170 | |||
171 | |||
172 | 1576 | dsschult | // the receive functions
|
173 | 1577 | dsschult | |
174 | /**@brief The main receive function. Dispatches packets for registered handlers and returns next basic packet if available. **/
|
||
175 | 1576 | dsschult | int8_t wl_get(char *data, uint8_t length);
|
176 | 1577 | dsschult | |
177 | /**@brief Returns the next basic packet if available. **/
|
||
178 | 1576 | dsschult | int8_t wl_get_basic(char *data, uint8_t length);
|
179 | 1577 | dsschult | |
180 | /**@brief Dispatches packets for registered handlers. **/
|
||
181 | 1576 | dsschult | int8_t wl_dispatch(void);
|
182 | |||
183 | 1577 | dsschult | |
184 | 1576 | dsschult | // the group register function
|
185 | 1577 | dsschult | |
186 | /**@brief Function to register new packet handlers (for non-default groups only). **/
|
||
187 | 1590 | dsschult | int8_t wl_register_handler(uint8_t group, FNPTR, uint8_t priority); |
188 | 1576 | dsschult | |
189 | 1598 | cmar | /**@brief Function to unregister existing packet handlers (for non-default groups only). **/
|
190 | int8_t wl_unregister_handler(uint8_t group); |
||
191 | |||
192 | 1581 | dsschult | /**@} **/ //end functions group |
193 | 1576 | dsschult | |
194 | 1581 | dsschult | /**@} **/ //end wireless group |
195 | 1576 | dsschult | |
196 | #endif |