{"id":20885426,"url":"https://github.com/lab11/gap","last_synced_at":"2025-12-27T09:17:14.912Z","repository":{"id":18222088,"uuid":"21362166","full_name":"lab11/gap","owner":"lab11","description":"802.15.4 and BLE cape for the BeagleBone Black","archived":false,"fork":false,"pushed_at":"2016-06-17T19:19:52.000Z","size":27250,"stargazers_count":15,"open_issues_count":1,"forks_count":7,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-01-19T10:43:37.123Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Eagle","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lab11.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-06-30T18:52:44.000Z","updated_at":"2021-05-09T08:57:18.000Z","dependencies_parsed_at":"2022-09-03T00:00:22.724Z","dependency_job_id":null,"html_url":"https://github.com/lab11/gap","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lab11%2Fgap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lab11%2Fgap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lab11%2Fgap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lab11%2Fgap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lab11","download_url":"https://codeload.github.com/lab11/gap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243267322,"owners_count":20263799,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-18T08:13:28.456Z","updated_at":"2025-12-27T09:17:14.846Z","avatar_url":"https://github.com/lab11.png","language":"Eagle","funding_links":[],"categories":[],"sub_categories":[],"readme":"GAP: Generic Access Point\n=========================\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"gap_rev3.png\" width=\"500\"\u003e\n\u003c/div\u003e\n\nGAP is the WiFi router for low-power and embedded Internet of Things devices.\nWhile WiFi routers provide ubiquitous Internet access for laptops and\nsmartphones, GAP provides Internet access for low-power sensors and wearable\ndevices. It supports both 802.15.4 and Bluetooth Low Energy.\n\nGAP is implemented as a cape for the\n[BeagleBone Black](http://beagleboard.org/black). It uses two TI CC2520 radios\nand a Nordic nRF51822 radio to provide connectivity. Each radio has a linux\nkernel module to allow userspace access to the radios.\n\nHardware\n--------\n\nThe GAP cape features a SPI interface to two CC2520\nradios, one of which is amplified with a CC2591, and one nRF51822 radio.\nIt also includes four LEDs.\n\n\nSoftware\n--------\n\nThe CC2520 radios are\n[supported natively](https://github.com/torvalds/linux/blob/master/drivers/net/ieee802154/cc2520.c)\nin newer versions of the Linux kernel (\u003e=4.1).\n\nThe nRF51822 BLE radio is a work-in-progress. It can be used as a standalone\nBLE radio (see [this repo](https://github.com/lab11/nrf5x-base) for a starting\npoint), but does not have great integration with the BBB at this point.\n\n\n\nSetting Up GAP\n--------------\n\nTo setup a BBB to work with GAP, follow these instructions:\n\n1. Start with a recent build of Debian for the BBB. We suggest starting\nwith pretty new version of Debian, like that can be found\n[here](http://elinux.org/Beagleboard:BeagleBoneBlack_Debian#Jessie_Snapshot_console).\n\n2. Once that is setup, ssh to the BBB and update the kernel to the newest\nversion. This will not only make sure you're running the latest code,\nbut also ensure all of the kernel modules will be present.\n\n        sudo apt-get update\n        sudo apt-get install vim git lsb-release\n        sudo /opt/scripts/tools/update_kernel.sh --beta --bone-channel\n\n    Luckily [Robert C Nelson](https://github.com/RobertCNelson/)\n    has made this really easy with a convenient script.\n\n3. Now we have to setup the device tree overlay to let Linux know that\nthe the radios exist. The GAP overlay and others are setup in a repository also\nmaintained by RCN.\n\n        git clone https://github.com/lab11/bb.org-overlays\n        cd bb.org-overlays\n        ./dtc-overlay.sh\n        ./install.sh\n\n    That puts the compiled overlay in the correct place, now we need to tell\n    the BBB to use it at boot.\n\n        vim /boot/uEnv.txt\n        # Edit that line that looks like this to include the reference to GAP\n        cape_enable=bone_capemgr.enable_partno=BB-GAP\n\n4. Reboot to apply this.\n\n        sudo reboot\n\n\n\nSniffing 15.4 Packets\n---------------------\n\nTo make sure everything is working, it is pretty easy to get Linux to\nprint out the packets the radio is receiving.\n\n1. Install the `wpan-tools` to configure all of the 15.4 devices.\n\n        sudo apt-get install pkg-config libnl-3-dev libnl-genl-3-dev\n        wget http://wpan.cakelab.org/releases/wpan-tools-0.5.tar.gz\n        tar xf wpan-tools-0.5.tar.gz\n        cd wpan-tools-0.5\n        ./configure\n        make\n        sudo make install\n\n1. Install `tcpdump` to view the packets.\n\n        sudo apt-get install tcpdump\n\n2. Configure the network devices. Be sure to set the channel and PANID\nto match what is transmitting the 15.4 packets.\n\n        iwpan phy phy0 set channel 0 11\n        iwpan dev wpan0 del\n        iwpan phy phy0 interface add wpan0 type node c0:98:e5:00:00:00:00:01\n        iwpan dev wpan0 set pan_id 0x0022\n        /sbin/ifconfig wpan0 up\n\n3. Use `tcpdump` to view them.\n\n        sudo tcpdump -i wpan0 -vvv\n        \n    OR, use a simple c program to read from the raw socket.\n    \n        cd linux\n        gcc recv_raw_802154.c -o raw\n        sudo ./raw\n        \n    OR, use a very similar python script:\n    \n        cd linux\n        sudo python recv_raw_802154.py\n        \n\n\nRPL Border Router\n----------------\n\nGAP can be setup as a border router running a 6LoWPAN based mesh network\nwith RPL as a routing layer. It uses [unstrung](https://github.com/mcr/unstrung)\nto provide the RPL implementation. The rest is supported by the Linux kernel.\n\nTo set this up:\n\n1. Setup the radios and network interfaces:\n\n        sudo iwpan phy phy1 set channel 0 23\n        sleep 15\n        sudo iwpan dev wpan1 del\n        sleep 15\n        sudo iwpan phy phy1 interface add wpan1 type node c0:98:e5:00:00:00:00:01\n        sleep 15\n        sudo iwpan dev wpan1 set pan_id 0x0022\n        sleep 15\n        sudo ip link add link wpan1 name lowpan1 type lowpan\n        sleep 15\n        sudo ifconfig lowpan1 up\n        sleep 15\n        sudo ifconfig wpan1 up\n\n   Note: I've found that putting a sleep between those commands makes everything run smoothly.\n   Calling them too quickly seems to break things (at least in the past, it's possible\n   that newer commits have solved this issue).\n\n2. Get unstrung.\n\n        git clone https://github.com/mcr/unstrung.git\n        cd unstrung\n        make\n\n    There may be commits that need to be applied to make this\n    work. Look at unstrung pull requests to see if there are\n    outstanding patches that are required.\n\n3. Run unstrung.\n\n        /home/debian/unstrung/programs/sunshine/sunshine --verbose --dagid 0x11112222333344445555666677778888 -i lowpan1 -W 10000 --stderr -R 1 --prefix 2607:f018:800:201:c298:e588:4400:1/64 -m\n\n4. You should be able to ping a node:\n\n        sudo ping6 2607:f018:800:201:c298:e522:2200:bb -s 16\n\n\n\u003c!--\n\n### Setup EEPROM\n\nNow we are getting close. We have told Linux about the kernel modules\nand added the device tree overlay to a place where Linux can find it.\nThe last step is to get Linux to load the overlay which will then cause\nit to load the kernel modules. This is where the EEPROM comes in.\n\nWhen the BeagleBone Black boots it checks for EEPROMs present on any capes\nand uses the configuration data in the EEPROM to load the correct device\ntree overlay.\n\nThere exists a utility to create the hexdump (data.eeprom) to flash to the\nEEPROM in `/software/utility`. After creating the hexdump, apply a jumper\nto the write header near the EEPROM chip and use this command to flash the\nEEPROM:\n\nChoose 12 characters to serve as the serial number, in\nthe form `WWYY\u0026\u0026\u0026\u0026nnnn`. From the SRM:\n\n    WW = 2 digit week of the year of production.\n    YY = 2 digit year of production.\n    \u0026\u0026\u0026\u0026 = Assembly code, up to you to decide.\n    nnnn = incrementing board number for week of production.\n\nAfter creating `data.eeprom` with the eepromflasher utilty, write it to the\ncape EEPROM as root.\n\n    # On the BBB\n    sudo su\n    cat data.eeprom \u003e /sys/bus/i2c/devices/1-0057/eeprom\n\nWhere `1-0057` is the default address for the GAP cape. This can be changed\nby using the solder jumper pads near the EEPROM on the upper left corner of the\nboard.\n\nUnfortunately, the BBB debian distribution fails to load custom firmware from\nthe EEPROM on boot, and requires an capemanager configuration file to be\nedited.\n\n    sudo vim /etc/default/capemgr\n\n    # Add this line:\n    CAPE=BB-BONE-GAP\n\n\nCC2520 Border Router\n--------------------\n\nOne way to use the CC2520s on GAP is with the TinyOS code in a related\nrepo: [RaspberryPi-CC2520](https://github.com/lab11/raspberrypi-cc2520).\nThe `BorderRouter` application can be compiled with `make gap`.\n--\u003e\n\n\u003c!--\n\n\n### EEPROM\n\nThe capes feature EEPROM that will allow for the BeagleBone capemgr to auto load the driver\nand configure pins on boot, in accordance with the Beaglebone Black SRM. There\nexists a utility to create the hexdump (data.eeprom) to flash to the EEPROM in\nbeaglebone-cc2520/software/utility. After creating the hexdump, apply a jumper\nto the write header and use this command to flash the EEPROM:\n\n```bash\ncat data.eeprom \u003e /sys/bus/i2c/devices/1-0057/eeprom\n```\n\nWhere 1-0057 is the default address for the Zigbeag cape. This can be changed by\nusing the solder jumper pads on the upper left corner of the board.\n\n\nSoftware\n--------\n\n### Install\n\nThis guide assumes the default Angstrom distro running under root.\u003cbr/\u003e\nClone the repo to wherever you feel fit:\n\n```bash\ngit clone https://github.com/lab11/beaglebone-cc2520.git\n```\n\nNote: you may have to follow the directions [here](http://derekmolloy.ie/fixing-git-and-curl-certificates-problem-on-beaglebone-blac/) to get git working correctly.\n\nAn install script is located in /software. \u003cbr/\u003e\nThe script will copy the Device Tree Overlay (DTO) to /lib/firmware, and the driver to /lib/modules/KERNEL_VERSION, where KERNEL_VERSION is your current running kernel version number. \u003cbr/\u003e\nNavigate to software/ and run the install script:\n\n```bash\ncd beaglebone-cc2520/software/\n./install\n```\n\nIf using the Zigbeag cape with configured EEPROM, just plug it in and reboot the beaglebone and your board will be fully functional.\n\nIf EEPROM is not configured, to load the Device Tree Overlay manually:\n\n```bash\necho BB-BONE-CC2520 \u003e /sys/devices/bone_capemgr.9/slots\n```\nThis command should complete with no output.\nTo check that the DTO has loaded, run:\n\n```bash\ncat /sys/devices/bone_capemgr.9/slots\n```\nNote: bone_capemgr.9 may actually be bone_capemgr.8 for different beaglebones. \u003cbr/\u003e\nYou should check to see that there is now an override board in a slot after the virtual HDMI cape. \u003cbr/\u003e\nHere is my output:\n\n```\n 0: 54:PF---\n 1: 55:PF---\n 2: 56:PF---\n 3: 57:PF---\n 4: ff:P-O-L Bone-LT-eMMC-2G,00A0,Texas Instrument,BB-BONE-EMMC-2G\n 5: ff:P-O-L Bone-Black-HDMI,00A0,Texas Instrument,BB-BONELT-HDMI\n 7: ff:P-O-L Override Board Name,00A0,Override Manuf,BB-BONE-CC2520\n```\n\nNow that the DTO is loaded, the pins are now muxed correctly for the cc2520 board. We can now load the driver with:\n\n```bash\nmodprobe cc2520\n```\n\nThis command should complete with no output. \u003cbr/\u003e\nYou can check that the driver loaded successfully with:\n\n```bash\nlsmod\n```\n\n\n#### Testing\nYou should now have a functioning Zigbeag cape. There are test programs located in software/driver/tests. Try running the write and read program on two beaglebones, and you should be able to see them talking to each other.\n\n#### Install Issues\nIf you run into issues with any of the above commands, check dmesg for any output from the kernel. \u003cbr/\u003e\nRun this to check for issues with loading the DTO:\n\n```bash\ndmesg | grep bone_capemgr\n```\n\nRun this to check for issues with loading the driver:\n\n```bash\ndmesg | grep cc2520\n```\n\n### Kernel Module\n\nIn order to support the CC2520, you need the kernel module located in software/driver. The install script will automatically copy this into /lib/modules/KERNEL_VERSION. \u003cbr/\u003e\nThis driver has been adapted from the [Linux CC2520 Driver](https:/github.com/ab500/linux-cc2520-driver). \u003cbr/\u003e\nIf you would like to compile the driver from source, there is some setup involved.\nI've found it easiest to use a symlink and compile from the current kernel on the Beaglebone.\n\n```bash\nopkg update\nopkg upgrade\n```\nIt would be a good idea to reboot at this point\n\n```bash\nopkg install kernel-headers\nopkg install kernel-dev\ncd /usr/src/kernel\nmake scripts\nln -s /usr/src/kernel /lib/modules/$(uname -r)/build\n```\n\nYou can then navigate to beaglebone-cc2520/software/driver and run make to compile the driver. Make sure you re-run the install script, which will copy cc2520.ko to /lib/modules/KERNEL_VERSION and run depmod -a to register the driver with your system. --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flab11%2Fgap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flab11%2Fgap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flab11%2Fgap/lists"}