{"id":13423236,"url":"https://github.com/bobbin-rs/bobbin-cli","last_synced_at":"2025-03-15T15:30:51.604Z","repository":{"id":57520780,"uuid":"91353804","full_name":"bobbin-rs/bobbin-cli","owner":"bobbin-rs","description":"A Rust command line tool to simplify embedded development and deployment.","archived":false,"fork":false,"pushed_at":"2020-01-12T19:58:23.000Z","size":173,"stargazers_count":114,"open_issues_count":8,"forks_count":8,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-02T15:44:24.489Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.bobbin.io/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bobbin-rs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-15T15:28:42.000Z","updated_at":"2024-11-14T07:29:45.000Z","dependencies_parsed_at":"2022-09-26T18:01:05.052Z","dependency_job_id":null,"html_url":"https://github.com/bobbin-rs/bobbin-cli","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/bobbin-rs%2Fbobbin-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobbin-rs%2Fbobbin-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobbin-rs%2Fbobbin-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobbin-rs%2Fbobbin-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bobbin-rs","download_url":"https://codeload.github.com/bobbin-rs/bobbin-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243750466,"owners_count":20342066,"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-07-31T00:00:25.691Z","updated_at":"2025-03-15T15:30:51.575Z","avatar_url":"https://github.com/bobbin-rs.png","language":"Rust","readme":"# Bobbin-CLI\n\nbobbin-cli is a tool designed to make it easy to build, deploy, test and debug embedded\ndevices using a unified CLI. bobbin-cli understands Rust's cargo / xargo package managers\nbut can also work with Make or any other build system.\n\nbobbin-cli has the following main areas of functionality:\n\n-  Device enumeration and selection. bobbin-cli recognizes many types of USB debuggers and loaders\n   and allows you to set per-project filters so that it knows which device to use even when\n   multiple devices are connected to your computer.\n\n-  Build management. bobbin-cli automatically uses xargo to build your project, and reads the\n   command line parameters and your Cargo.toml file to automatically determine the output binary\n   to use. You can also use Make, with a required parameter to specify the output binary path.\n\n-  Deployment. For supported devices, bobbin-cli can automatically use the appropriate flash\n   loading tool (OpenOCD, JLinkExe, bossac or teensy_cli_loader) to upload the output binary.\n\n-  Testing and Debugging. bobbin-cli can automatically connect to and display the virtual serial\n   console of the selected device if available. You can also start an instance of OpenOCD and gdb with\n   the output binary produced by the build stage.\n\nFor a collection of LED blinking demos for a wide variety of popular development boards,\nsee [bobbin-blinky](https://github.com/bobbin-rs/bobbin-blinky/).\n\n## Host Platforms\n\nMacOS and Linux are currently supported, Windows support is planned.\n\n## Supported Devices\n\n### Debug Probes\n\nCurrently Supported:\n\n- [J-Link](https://www.segger.com/products/debug-probes/j-link/) - including CDC (virtual serial port) support.\n- [ST-Link/V2](http://www.st.com/en/development-tools/st-link-v2.html) - V2 and V2.1 devices supported,\nincluding CDC (virtual serial port) and SWO Trace (optional, requires libusb).\n- [CMSIS-DAP](https://developer.mbed.org/handbook/CMSIS-DAP) - including CDC (virtual serial port) support.\n- [DAPLINK](https://github.com/mbedmicro/DAPLink) - including MSD (mass storage device) and CDC (virtual serial port) support.\n- [TI ICDI](http://www.ti.com/tool/stellaris_icdi_drivers) - including CDC (virtual serial port) support.\n- [Black Magic Probe](https://github.com/blacksphere/blackmagic) - including CDC (virtual serial port) support.\n\nComing Soon:\n\n- [PEmicro](http://www.pemicro.com/opensda/)\n\n### Development Boards with Embedded Debug Probes\n\nBoards from the following product families include embedded debug probes that should be supported.\n\n- [STM32 Discovery](http://www.st.com/en/evaluation-tools/stm32-mcu-discovery-kits.html?querycriteria=productId=LN1848) \n- [STM32 Nucleo](http://www.st.com/en/evaluation-tools/stm32-mcu-nucleo.html?querycriteria=productId=LN1847)\n- [Freescale FRDM](http://www.nxp.com/products/software-and-tools/hardware-development-tools/freedom-development-boards:FREDEVPLA)\n- [TI Launchpad](http://www.ti.com/lsds/ti/tools-software/launchpads/overview/overview.page)\n- [NXP S32K144EVB](http://www.nxp.com/products/automotive-products/microcontrollers-and-processors/arm-mcus-and-mpus/s32-processors-microcontrollers/s32k144-evaluation-board:S32K144EVB)\n- [Arduino Zero](https://www.arduino.cc/en/Guide/ArduinoZero)\n\n*Note:* Many development boards support OpenSDA, which allows a choice of firmware to be installed. Debug probes may support\nCMSIS-DAP, DAPLINK, J-Link and PEMicro firmware variants. Be sure to upgrade to the most recent firmware available, and ensure that\na variant supporting OpenOCD (CMSIS-DAP/DAPLINK) or J-Link is installed. Please see [Upgrading Development Board Firmware](FIRMWARE.md).\n\n### Development Boards with Flash Loader Support\n\nBoards from the following product families use flash loaders that are supported.\n\n- [Feather M0/M4](https://www.adafruit.com/feather) and other Adafruit boards with UF2 bootloaders\n- [Teensy 3.x and LC](https://www.pjrc.com/teensy/)\n- STM32 DFU Bootloader\n\n## Prerequisites\n\n### Build Tools\n\nThese tools must be installed in your PATH.\n\n- [GNU ARM Embedded](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm)\n- [xargo](https://github.com/japaric/xargo)\n\n### Debugger / Loader Tools\n\nYou must have the appropriate tools installed for the debug probes / dev boards that you wish to use.\n\n- [OpenOCD](http://openocd.org) - 0.10 or later required for STLink, DAPLINK, CMSIS-DAP, and TI ICDI debug probes\n- [J-Link](https://www.segger.com/downloads/jlink) - required for J-Link debug probes.\n- [Bossa](http://www.shumatech.com/web/products/bossa) - required for Arduino and Feather devices\n- [Teensy Loader](https://www.pjrc.com/teensy/loader_cli.html) - required for Teensy devices\n- [libusb](http://libusb.info) - required for STLink SWO Trace support.\n- [dfu-util](http://dfu-util.sourceforge.net) - required for STM32 DFU Bootloader support\n\n### Development Board Firmware\n\nIf you are using a development board with embedded debug probe, check that you know what debug firmware you have\ninstalled and that it is up to date. Please see [Development Board Firmware](FIRMWARE.md).\n\n## Installation\n\n*Note:* Only Linux and macOS hosts are supported at this time.\n\nTo install from cargo:\n\n```\n$ cargo install bobbin-cli\n```\n\nTo install from github:\n\n```\n$ git clone https://github.com/bobbin-rs/bobbin-cli.git\n$ cd bobbin-cli\n$ cargo install\n```\n\nTo install with ST-Link SWV Trace support:\n\n```\n$ cargo install --features stlink\n```\n\n## Usage\n\nThe name of the executable is `bobbin`.\n\n### Help\n\nYou can display detailed help text by using `bobbin -h`.\n\n### Bobbin Check\n\nUse \"bobbin check\" to list the version numbers of all Bobbin dependencies. \"Not Found\" will be displayed if\nthe dependency is not available.\n\n```\n$ bobbin check\n      Rust 1.20.0-nightly (83c659ef6 2017-07-18)\n     Cargo 0.21.0-nightly (f709c35a3 2017-07-13)\n     Xargo 0.3.8\n       GCC 5.4.1 20160919 (release) [ARM/embedded-5-branch revision 240496]\n   OpenOCD 0.10.0+dev-00092-g77189db (2017-03-01-20:42)\n     JLink V6.15c (Compiled Apr 24 2017 19:07:08)\n     Bossa 1.7.0\n    Teensy 2.1\n  dfu-util 0.9\n```\n\nPlease include the \"bobbin check\" output when reporting problems.\n\n### Bobbin List\n\nUse \"bobbin list\" to view all debug probes and development boards connected to your host.\n\n```\n$ bobbin list\nID       VID :PID  Vendor                   Product                          Serial Number\n4c01a4ad 1366:0105 SEGGER                   J-Link                           000621000000\n14a7f5da 03eb:2157 Atmel Corp.              EDBG CMSIS-DAP                   00000000EZE000005574\nb7e67550 0483:374b STMicroelectronics       STM32 STLink                     0673FF485550755187121723\na3ef65e3 0483:374b STMicroelectronics       STM32 STLink                     0667FF555654725187073723\ncb46720d 1cbe:00fd Texas Instruments        In-Circuit Debug Interface       0F007E1A\n8c6bbec5 0d28:0204 ARM                      DAPLink CMSIS-DAP                0260000025414e450049501247e0004e30f1000097969900\nf95f4aca 0d28:0204 ARM                      DAPLink CMSIS-DAP                0240000034544e45001b00028aa9001a2011000097969900\nc2f3dc42 0483:374b STMicroelectronics       STM32 STLink                     0670FF484957847167071621\n$\n```\n\nThe device ID is a hash of the USB Vendor ID, USB Product ID, and USB Serial Number (if available). \"bobbin list\" displays\nthe first eight hex digits of the device ID, and \"bobbin info\" displays the full 64 bit ID.\n\n### Bobbin Info\n\nTo view detailed information about a devices, use the \"bobbin info\" subcommand.\n\n```\n$ bobbin -d 4c01 info\nID               c2f3dc42b4aadc58b6dfa98ce527dd436e3e4fa5\nVendor ID        0483\nProduct ID       374b\nVendor           STMicroelectronics\nProduct          STM32 STLink\nSerial Number    0670FF484957847167071621\nType             STLinkV21\nLoader Type      OpenOCD\nDebugger Type    OpenOCD\nCDC Device       /dev/cu.usbmodem141413\nOpenOCD Serial   hla_serial 0670FF484957847167071621\n$\n```\n\nIf you have more than one connected device, you can select a specific device by using the -d command line\nparameter. bobbin-cli will also look for a device filter directive in a YAML configuration file at ./bobbin/config\n\n```\n$ cat .bobbin/config\n[filter]\ndevice = \"c2f3dc42\"\n```\n\n### Bobbin Build\n\n`bobbin build` runs xargo (by default) or make to build your application. If using xargo, bobbin-cli will\npass through any --target, --bin, --example or --release parameters. \n\nOn completion, bobbin-cli will run `arm-none-eabi-size` on the binary and display the output.\n\n```\n$ bobbin build\n   Compiling blue-pill v0.1.0 (file:///home/bobbin/bobbin-blinky/blue-pill)\n    Finished dev [optimized + debuginfo] target(s) in 0.50 secs\n   text\t   data\t    bss\t    dec\t    hex\tfilename\n    152\t      0\t      4\t    156\t     9c\ttarget/thumbv7em-none-eabihf/debug/blue-pill\n$\n```\n\n### Bobbin Load\n\n`bobbin load` runs `bobbin build` and then, if successful, load the binary onto the device\nusing the selected debugger or loader, using objcopy as needed to convert to the appropriate\nformat. You may include --target, --bin, --example or --release parameters which will be passed\nto `bobbin build`.\n\n`bobbin load` will interpret the build parameters as well as the Cargo.toml file to determine\nthe path to the binary.\n\n```\n$ bobbin load\n   Compiling blue-pill v0.1.0 (file:///home/bobbin/bobbin-blinky/blue-pill)\n    Finished dev [optimized + debuginfo] target(s) in 0.13 secs\n   text\t   data\t    bss\t    dec\t    hex\tfilename\n    152\t      0\t      4\t    156\t     9c\ttarget/thumbv7em-none-eabihf/debug/blue-pill\n     Loading target/thumbv7em-none-eabihf/debug/blue-pill.hex\n    Complete Successfully flashed device\n      Loader Load Complete\n$\n```\n\n\nSome devices require manual intervention to enter bootloader mode; you should do this before\nrunning `bobbin load`.\n\n*Note: Many debuggers and loaders require additional configuration*\n\n- OpenOCD: a properly configured openocd.cfg file must be in the current directory. bobbin will add \nthe appropriate OpenOCD command line parameters to select the specific device.\n- J-Link: you must specify the device type through the --jlink-device command line parameter or\nin the .bobbin/config file.\n- Teensy Loader: you must specify the device type through the --teensy-mcu command line parameter or\nin the .bobbin/config file.\n\n### Bobbin Run\n\n`bobbin run` runs `bobbin load` and then, if successful, open the serial console of the\nconnected device to display the output. Use Control-C to terminate this console viewer.\n\nIf the selected device does not have an associated serial port, that step will be skipped. \n\nYou can use the --console parameter to manually specify a serial device, or --noconsole if \nyou do not want run the console viewer at all.\n\n*Note: the serial viewer is currently hard-coded to 115,200 baud*\n\nIf bobbin-cli is compiled with support for SWO trace, you can pass the --itm parameter\nto display ITM output instead of running the serial console. You will also need to pass\nthe --itm-target-clock parameter with the target's clock speed.\n\n```\n$ bobbin run\n   Compiling blue-pill v0.1.0 (file:///home/bobbin/bobbin-hello/blue-pill)\n    Finished dev [optimized + debuginfo] target(s) in 0.13 secs\n   text\t   data\t    bss\t    dec\t    hex\tfilename\n    152\t      0\t      4\t    156\t     9c\ttarget/thumbv7em-none-eabihf/debug/blue-pill\n     Loading target/thumbv7em-none-eabihf/debug/blue-pill.hex\n    Complete Successfully flashed device\n      Loader Load Complete\n     Console Opening Console\nHello World 1\nHello World 2\nHello World 3\n^C\n$\n```\n\n### Bobbin Test\n\n`bobbin test` runs `bobbin run` and then interprets the serial output, looking for\ntags indicating test progress and completion.\n\n```\n$ bobbin test\n   Compiling frdm-k64f v0.1.0 (file:///home/bobbin/bobbin-boards/frdm-k64f)\n    Finished dev [optimized + debuginfo] target(s) in 0.61 secs\n   text\t   data\t    bss\t    dec\t    hex\tfilename\n   6252\t    428\t    408\t   7088\t   1bb0\ttarget/thumbv7em-none-eabihf/debug/frdm-k64f\n     Loading target/thumbv7em-none-eabihf/debug/frdm-k64f\n    Complete Successfully flashed device\n      Loader Load Complete\n     Console Opening Console\n[start] Running tests for frdm-k64f\n[pass] 0\n[pass] 1\n[pass] 2\n[pass] 3\n[pass] 4\n[done] All tests passed\n$\n```\n\n`bobbin test` recognizes [start], [pass] and [done] tags, exiting with return code 0. It also recognizes\n[fail], [exception], and [panic] tags, which will cause it to exit with return codes 1, 2 or 3. All other\noutput is ignored.\n\nThe test runner will exit with return code 1 if there is a delay of more than 5 seconds between lines\nor 15 seconds to complete the entire test. In the future these timeouts will be configurable.\n\n### Additional Subcommands\n\n`bobbin reset` resets the target device.\n\n`bobbin halt` halts the target device, if supported.\n\n`bobbin resume` resumes the target device, if supported.\n\n`bobbin console` starts a console viewer session using the selected device's serial port at a speed\nof 115,200.\n\n`bobbin itm` starts an itm viewer session using the selected device.\n\n`bobbin screen` starts a `screen` session using the selected device's serial port at a speed\nof 115,200.\n\n`bobbin openocd` starts an `openocd` session using the selected device.\n\n`bobbin jlink` starts a JLinkGDBServer session using the selected device.\n\n`bobbin gdb` starts a GDB session with the current target binary as the executable. For debug probes\nthat are GDB native, this command will connect directly to the device; for debug probes using\nOpenOCD or JLinkGDBServer, you must use `target remote :3333` manually or in a .gdbinit file.\n\n### Specifying Binary Targets\n\nIf you are not using xargo / cargo as your build manager, you have the option of specifying the output binary\npath as the first unlabeled argument. For instance:\n\n$ bobbin run build/blinky.elf\n\nwould use build/blinky.elf as the target binary to run.\n\n$ bobbin test build/blinky.elf\n\nwould load and test build/blinky.elf \n\n## Configuration\n\n### Selecting a device\n\nIf you have multiple debug probes connected, you can tell Bobbin which device to use on a per-directory basis.\nBobbin will look for a TOML configuration file in the .bobbin directory (.bobbin/config).\n\nTo select a specific device, create a [filter] section with a \"device\" key that includes the prefix of the\ndevice id. For instance,\n\n```\n$ bobbin list\nID       VID :PID  Vendor                   Product                          Serial Number\nf95f4aca 0d28:0204 ARM                      DAPLink CMSIS-DAP                0240000034544e45001b00028aa9001a2011000097969900\n8c6bbec5 0d28:0204 ARM                      DAPLink CMSIS-DAP                0260000025414e450049501247e0004e30f1000097969900\ncb46720d 1cbe:00fd Texas Instruments        In-Circuit Debug Interface       0F007E1A\n\n$ mkdir .bobbin\n$ cat \u003e test\n[filter]\ndevice = \"f95f4aca\"\n$ bobbin list\nID       VID :PID  Vendor                   Product                          Serial Number\nf95f4aca 0d28:0204 ARM                      DAPLink CMSIS-DAP                0240000034544e45001b00028aa9001a2011000097969900\n```\n\n### OpenOCD\n\nWhen using a debug probe / development board that uses OpenCD, you must have an openocd.cfg file in your\nproject directory that provides the correct configuration for the debugger and device being used.\n\nFor instance, for the FRDM-K64F:\n\n```\n$ cat openocd.cfg\nsource [find interface/cmsis-dap.cfg]\nsource [find target/kx.cfg]\nkx.cpu configure -event gdb-attach { reset init }\n```\n\nYou should be able to run \"openocd\" and have it successfully connect to the device, assuming you only have\na single debug probe of that type connected:\n\n```\n$ openocd\nOpen On-Chip Debugger 0.10.0+dev-00092-g77189db (2017-03-01-20:42)\nLicensed under GNU GPL v2\nFor bug reports, read\n\thttp://openocd.org/doc/doxygen/bugs.html\nInfo : auto-selecting first available session transport \"swd\". To override use 'transport select \u003ctransport\u003e'.\nInfo : add flash_bank kinetis kx.flash\nadapter speed: 1000 kHz\nnone separate\ncortex_m reset_config sysresetreq\nInfo : CMSIS-DAP: SWD  Supported\nInfo : CMSIS-DAP: Interface Initialised (SWD)\nInfo : CMSIS-DAP: FW Version = 1.0\nInfo : SWCLK/TCK = 0 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1\nInfo : CMSIS-DAP: Interface ready\nInfo : clock speed 1000 kHz\nInfo : SWD DPIDR 0x2ba01477\nInfo : MDM: Chip is unsecured. Continuing.\nInfo : kx.cpu: hardware has 6 breakpoints, 4 watchpoints\n^C\n$\n```\n\nBobbin will invoke OpenOCD with additional command line parameters specifying the USB serial number\nof the device to open.\n\n### J-Link\n\nJ-Link debug probes require a device identfier that specifies the target MCU. You must specify this by using the\n--jlink-device=\u0026lt;JLINK-DEVICE\u0026gt; command line parameter or by adding a jlink-device key to the [loader] section\nof your .bobbin/config file:\n\n```\n[loader]\njlink-device = \"S32K144\"\n```\n\nYou may view a list of devices at [J-Link - Supported Devices](https://www.segger.com/products/debug-probes/j-link/technology/cpus-and-devices/j-link-supported-devices/).\n\n### Teensy Loader\n\nteensy_loader_cli requires an additional command line parameter --teensy-mcu=\u0026lt;MCU\u0026gt; that tells it the exact MCU being used. You\nwill need to add a teensy-mcu key to the [loader] section of your .bobbin/config file:\n\n```\n[loader]\nteensy-mcu = \"mk20dx256\" # Teensy 3.2\n```\n```\n[loader]\nteensy-mcu = \"mk64fx512\" # Teensy 3.5\n```\n```\n[loader]\nteensy-mcu = \"mk66fx1m0\" # Teensy 3.6\n```\n```\n[loader]\nteensy-mcu = \"mkl26z64\" # Teensy LC\n```\n\nUse 'teensy_loader_cli --list-mcus' to view a list of supported MCUs.\n\n### BOSSA\n\nIf you have `bossac` 1.9 or later, or 1.8 and an M4 board, you may need to\nspecify the offset address to start the flashing. This is because by default\n`bossac` will start flashing at address 0x0000, which is likely where your\nlocked bootloader is located.\n\nThese values seem to work for Adafruit M0/M4 devices with their UF2 bootloader,\nsuch as Feather M0/M4, Circuit Playground Express, and NeoTrellis M4:\n\n * For M0 devices, use `--offset 0x2000`\n * For M4 devices, use `--offset 0x4000`\n\nYou can also specify this in the [loader] section of your .bobbin/config file:\n\n```\n[loader]\noffset = \"0x2000\" # M0\n```\n```\n[loader]\noffset = \"0x4000\" # M4\n```\n\n\nFor more information about the UF2 bootloader and BOSSA, see Adafruit’s\n[UF2 Bootloader Details](https://learn.adafruit.com/adafruit-feather-m0-express-designed-for-circuit-python-circuitpython/uf2-bootloader-details) page.\n","funding_links":[],"categories":["Tools"],"sub_categories":["Community Chat Rooms","Paid and commercially available materials"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobbin-rs%2Fbobbin-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbobbin-rs%2Fbobbin-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobbin-rs%2Fbobbin-cli/lists"}