WirelessLibrary

Work on this in the wireless branch.

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
  • 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
    • 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.

DSCF3451.JPG - 11/11/2009 Meeting - Whiteboard (1.4 MB) James Kong, 11/11/2009 08:57 pm

rx_packet_structure.jpg (41 KB) David Schultz, 11/11/2009 11:38 pm

colony_wireless_api_v1.txt Magnifier - Rough Draft of New API (1.88 KB) Chris Mar, 11/23/2009 12:02 pm