WirelessLibrary¶

Work on this in the wireless branch.

• WirelessLibrary
  • Notes from spring 2010 work
  • Public API
  • Redoing Wireless
    • Code compiles now, so write test cases and test on the robot - 1/20/10
    • Divide work into separate sections - 11/23/09
    • New Wireless API - Chris, David, Ben, Evan - 11/18/09
    • Wireless Architecture - James, Chris, Brad, David, Evan, Ben & BRIAN - 11/11/09
    • Discussion - James, Chris, Brad, David, others - 11/4/09
    • The UDP/TCP Approach - David - 11/2/09

Notes from spring 2010 work¶

• Debug options
  • should move this to makefile, or a command option when running makefile (make debug?)
• buffer size
  • this is currently set to 250 bytes
  • should try to lower this and find ideal size
• doxygen
  • needs to be posted on redmine
• ackreset()
  • needs to reset send_buffer as well
• ackhandle()
  • case 0 should be right
  • other cases have an error somewhere
• xbee_reset()
  • not implemented yet
  • should recover from any state, any mode, etc
• xbee_interrupt
  • should check checksum
    • need to implement user-level acking
  • should implement high priority group handling
• check_last_received()
  • needs to be tested
• functions should all check that the library has been initialized
• basic packets
  • there's some sort of bug with larger packet sizes

• comments
  • go over comments and make sure they actually correspond to the functions that are written

• old libwireless functions
  • see if you can make deprecated references from old function names to the new ones

• libdragonfly
  • the copy in the branch does init() checking
    • although not very well, since one of the init() calls is out of order
    • currently doesn't run rangefinders correctly

• computer code in jar file in base folder of branch
  • this is from my 15-437 webapps project

Public API¶

note: doxygen version of API is available in wireless branch (branches/wireless/docs/libwireless/html)

//send functions

/**
 * The core send function. This will take all possible arguments and send all types of packets.
 * 
 * @param data pointer to the byte array of data to be included in the packet
 * @param length the length of the data array
 * @param group the packet group of the packet
 * @param scope flag for sending global packet or your current PAN
 * @param dest robot ID (for robot to robot packet)
 * @param mode flag for using FAST or RELIABLE sending
 *
 * @return positive packet number for tracking acks, or error code
 **/
int16_t wl_send(uint8_t *data, uint8_t length, uint8_t group, uint8_t scope, uint16_t dest, uint8_t mode)

/**
 * Wrapper for core send function that will send a global packet across the current channel.
 *
 * @param data pointer to the byte array of data to be included in the packet
 * @param length the length of the data array
 * @param group the packet group of the packet
 *
 * @return positive packet number for tracking acks, or error code
 **/
int16_t wl_send_global(uint8_t *data, uint8_t length, uint8_t group)

/**
 * Wrapper for core send function that will send a packet across the current channel on the current pan.
 *
 * @param data pointer to the byte array of data to be included in the packet
 * @param length the length of the data array
 * @param group the packet group of the packet
 *
 * @return positive packet number for tracking acks, or error code (TBD)
 **/
int16_t wl_send_pan(uint8_t *data, uint8_t length, uint8_t group)

/**
 * Wrapper for core send function that will send a packet across the current channel to a specific robot. 
 *
 * @param data pointer to the byte array of data to be included in the packet
 * @param length the length of the data array
 * @param group the packet group of the packet 
 * @param dest robot ID (for robot to robot packet)
 * @param mode flag for using FAST or RELIABLE sending
 *
 * @return positive packet number for tracking acks, or error code (TBD)
 **/
int16_t wl_send_robot(uint8_t *data, uint8_t length, uint8_t group, uint16_t dest, uint8_t mode)

/**
 * Default (i.e. basic) send wrapper.
 *
 * @param data pointer to the byte array of data to be included in the packet
 * @param length the length of the data array
 *
 * @return positive packet number for tracking acks, or error code (TBD)
 **/
int16_t wl_send_basic(uint8_t *data, uint8_t length)

// TCP Acknoledgment (ACK) functions

/**
 * acknowledgment error
 * check if any of the packets you have sent have been lost.
 *
 * note that all other error checking will be handled by library, 
 * so your user behavior won't have to worry about it
 *
 * @return the # of packets lost (up to 255)
 **/
uint8_t wl_ack_error(void)

/**
 * acknowledgement error check
 * check if a specific packet has been lost
 * note: buffer will overflow every 255 packets
 * 
 * @param packet packet number
 *
 * @return {SENDING,ACK_OK,ACK_FAILURE,CCA_FAILURE}
 **/
int8_t wl_ack_check(uint8_t packet)

/**
 * acknowledgement reset
 * reset the acknowledgement buffer
 **/
void wl_ack_reset(void)

// receive functions
/**
 * the main receive function (similar to wl_do)
 * 
 * when called, this function will receive the next packet on the default packet group
 * it will also dispatch registered packet handler functions for any other packet groups it has received
 *
 * @param data an already-initialized array to store the default group packet data in
 * @param length the length of the initialized data array
 *
 * @return the length of the used portion of data array or error (<0)
 **/
int8_t wl_get(char *data, uint8_t length)

/**
 * function to receive only packets on the default group
 * this function is only meant to receive packets sent using wl_send_basic()
 * 
 * @param data an already-initialized array to store the default group packet data in
 * @param length the length of the initialized data array
 * 
 * @return the length of the used portion of data array or error (<0)
 **/
int8_t wl_get_basic(char *data, uint8_t length)

/*
 * function to dispatch all registered packet handlers for received packets on non-default groups
 *
 * @return error codes
 */
int8_t wl_dispatch(void)

// packet handler registration functions
/**
 * function to register new packet handlers (for non-default groups only)
 *
 * @param group the packet group number of the packets to handle with this function
 * @param func the function pointer to the user-specified packet handler
 * @param priority flag to set the priority of the function handler
 *
 * @return 0 on success, or error code
 **/
int8_t wl_register_handler(uint8_t group, FNPTR, uint8_t priority)

/**
 * function to unregister existing packet handlers (for non-default groups only)
 *
 * @param group the packet group number of the handler to unregister
 *
 * @return 0 on success, or error code
 **/
int8_t wl_unregister_handler(uint8_t group)

// library initialization and termination
/**
 * initialization function:
 * set up xbee communication and packet handler infrastructure
 *
 * @return 0 on success, or error code
 **/
int8_t wl_init(void)

/**
 * termination function:
 * end xbee communication, deregister all handlers, etc
 *
 * @return 0 on success, or error code
 **/
int8_t wl_terminate(void)

Redoing Wireless¶

Wireless programming (high level code) needs to be redone. (xbee.c should be mostly fine)

Code compiles now, so write test cases and test on the robot - 1/20/10¶

• Test Cases
  • Xbee testing
    • test init - (PASSED - 1/20/10)
    • test terminate
    • test API mode 0
      • command testing
      • low level send
      • low level receive
    • test API mode 1
      • command testing
      • send packet
      • receive packet
    • test API mode 2 (not finished yet)
      • command testing
      • send packet
      • receive packet
  • Wireless testing
    • sending
      • test send global
      • test send pan
      • test send individual robot
      • test send basic
    • receiving
      • test receive global
      • test receive pan
      • test receive individual robot
      • test receive basic
    • packet groups
      • test add/delete packet groups
      • test send/receive packet groups

Divide work into separate sections - 11/23/09¶

• Send Functions
  • Core send function - David
  • Send wrappers - Ben
  • Ack system - David
• Receive Functions
  • Dispatch - Abe
  • Basic - Abe
• Common Functions
  • Init, Terminate - Chris
  • Packet group handler registration - Chris
• Xbee Functions
  • integrate serial.c xbee functions into xbee.c - Evan
  • other maintenance - Evan
  • modify receive interrupt - David
• Wireless behaviors/tools
  • high level ack system - Ben
    • other robot will explicitly ack packets in a set packet group (super reliable)
  • xbee dongle interface program -
    • will init xbee on computer, then wait for commands from user

New Wireless API - Chris, David, Ben, Evan - 11/18/09¶

• packet structure
  • frame ID (one byte)
  • group # (one byte or part of one)
  • data

• xbee.c is almost fine
  • integrate serial.c xbee functions into xbee.c
  • check for infinite waits
  • rename xbee_set/get_channel() and xbee_set/get_pan() to be called from global namespace
  • use API mode 2
    • this means checking for the three escaped characters and dealing with that
• user-registerable functions to be called in interrupt (or when packet is received)
• send functions
  • one core send function
    • generate packet ID # (software check on 1 or 2 bytes), save entire frame for ACKing and retries
    • check for escapeable characters (use API mode 2), set smaller max packet size
    • specific wrappers to fill in defaults
    • send global
      • only UDP b/c XBee doesn't provide enough info, to be added later
    • send to PAN
      • only UDP
    • send to robot
    • arguments for TCP/UDP, group, data, length, (dest robot)
    • super send function (default)
      • defaults to send global TCP, main group
      • can only send text (strings) - figure out string length (possible null character)
  • for TCP mode
    • only supported in robot-to-robot sending
    • auto ACK
      • only for robot-to-robot TCP
      • handle in send file
      • non-blocking ACK check
      • receive interrupt will check ACK buffer if we receive a response (ACK) packet
      • save number of retries for "no ACK" or "CCA failure" packets
      • remove old un-ACKed packets from buffer after three software retries
• receive functions
  • two types of returns to user
    • default: basic string
    • all relevant information (src robot, packet group, etc...)
      • support registering function pointers (one per group)
        • registration function will take three args: group number/name, function pointer, priority (i.e. handle this now)
  • timeout handler
    • check for repeat packet (save last 10 or so packet ID #s)
    • if packet group is high priority, handle it now
    • else, put it in buffer
  • wl_do (renamed to wl_get_packet?) called by user
    • check the buffer, check group of packet
    • default to returning the buffer, can also call function pointers
    • user behavior can trigger it with the rtc (re-write rtc to handle multiple function pointers)
      • init with a more advanced version of wl_init()
• init functions
  • core init
    • rtc arguments
    • default to pre-existing channel, PAN
  • wrapper function (default)
    • don't register for rtc
  • register function pointers after init
• files
  • send
  • receive
  • common
    • init functions
• computer code
  • only difference is xbee.c
  • focus on robot for now

Wireless Architecture - James, Chris, Brad, David, Evan, Ben & BRIAN - 11/11/09¶

• Lot's of discussion, see attached picture of whiteboard
  • DSCF3451.JPG
  • Eventually should be parsed into text here
• Chris will look at the Packet, ACK, and NACK headers for determining when they are fully received
  • When a robot sends a packet, the XBee module sends a "TX Status" message back to the robot
  • This packet includes the Frame ID (packet number) of the corresponding sent packet
  • It also specifies three possible statuses
    • 0 = Success
    • 1 = No ACK received (packet was not received by destination)
    • 2 = CCA Failed (packet was not sent - too much traffic on the network to send)
• David will look into re-transmits on the XBee and getting a list of other nearby active XBee IDs from the XBee
  • Re-Transmits
    • MAC Layer: fixed at 3 retransmit attempts (timeout = short)
    • XBee: 0-6 retransmit attempts (default 0) (timeout = 200 ms)
    • Library: whatever we want
  • List of active Xbee IDs
    • ND command (node discover)
      • only finds ids on current channel and pan
      • can scan all pans by switching to pan=broadcast before sending ND command
      • defaults to 2.5s, can shorten to 100ms
    • AS command (active scan)
      • can scan all channels and pans
      • returns a ton of information
      • takes a while (0.18s - 50min) since it uses an exponential timeout
  • Take a look to see what a received data packet looks like
    • rx_packet_structure.jpg
  • To clarify sending rules:
    • you can send to an individual robot on the PAN, or all robots on the PAN
    • or an individual robot anywhere on the channel, or all robots on the channel
  • Also, to clarify the hardware acks, this is sent by the MAC layer upon successful receipt of any robot-to-robot packet, unless it is specifically not requested. For sending to an entire PAN or channel, no ack is sent. The sender (application layer) will get a transmit response packet with the success or failure of the ack.
    • packet corruption or dropped packets will incur the sending timeout and be counted as ack failure
    • CCA failure (network is too busy to send packet) is another failure code (we might want to consider switching to a different channel in this case)
  • notes on xbee transmit speed:
    • 9600 baud sends at 2-3 kB/s
    • 115200 baud sends at 14.6 kB/s
    • by my calculations, the atmega128 is running at 2 Mhz. If this is wrong, please tell me

Discussion - James, Chris, Brad, David, others - 11/4/09¶

• High Priority
  • change channel for private communication
  • for high bandwidth situations
  • timeout with keepalives to reset channel
• separate robot and computer code
  • shared headers, and separate headers and c files
• channel partition
  • see here
• Time-dependent
  • some packets need to be handled immediately (token ring)
    • trigger interrupt
  • other packets can wait a bit
    • program dependent (wl_do)
• Programming Header (1 byte)
  • Group (5 bits)
  • Priority (1 bit)
  • (2 reserved bits)
    • Do we need to worry about escaping characters?
• Remove packet type (only have group to differentiate packets)
  • user can define other parameters and transmit them in the data
• Max Packet Length
  • ~100 char buffer limit
  • trigger interrupt if we reach the limit
• Handling Packets
  • include default handlers for certain groups of packets
    • ex) default sending/receiving strings, ColoNet,
  • allow user to define their own groups and handlers
  • handle response to sent packet within library
    • attempt to resend packet if it was lost, etc...

The UDP/TCP Approach - David - 11/2/09¶

• Implement basic UDP messaging
  • Basic Idea
    • Allows packets to be received by all robots on a channel
    • No verification of success or failure
  • Why this is a good thing
    • Many things, like the sensor matrix data, should be sent to all robots anyway
    • This avoids any delays caused by sending and checking for acks
  • Implementation Details
    • This is very simple, just change the packet destination to XBEE_BROADCAST
    • Can send a string directly through xbee_send_packet()
• Implement pseudo-TCP messaging
  • Basic Idea
    • Reliability
    • Error-free
    • If we wanted, we could also do ordered data, congestion control, etc
  • Why
    • Wireless likes to drop packets, or otherwise have problems
    • This would mostly take care of those issues
  • Implementation Details
    • Use something similar to TCP, but cut down the header size significantly
    • If we consider each packet as a self-contained message and don't care about order, we don't have to open or close a connection, just make sure this packet number is unique
    • Sending packets and checking acks/resending would be handled by the library
    • For packet groups, would just need a character to distinguish the packet group and a receive handler.