{"id":13423291,"url":"https://github.com/riscv-rust/longan-nano","last_synced_at":"2025-03-15T15:30:54.219Z","repository":{"id":45253539,"uuid":"215647417","full_name":"riscv-rust/longan-nano","owner":"riscv-rust","description":"Board support package for the Longan Nano board","archived":false,"fork":false,"pushed_at":"2024-11-24T19:31:37.000Z","size":119,"stargazers_count":117,"open_issues_count":5,"forks_count":31,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-11-24T20:30:04.665Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.seeedstudio.com/Sipeed-Longan-Nano-RISC-V-GD32VF103CBT6-Development-Board-p-4205.html","language":"Rust","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/riscv-rust.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-16T21:25:36.000Z","updated_at":"2024-11-24T19:31:42.000Z","dependencies_parsed_at":"2024-10-26T21:56:03.747Z","dependency_job_id":"02e87d05-4326-4b7f-a392-de8b1f581cb8","html_url":"https://github.com/riscv-rust/longan-nano","commit_stats":{"total_commits":91,"total_committers":15,"mean_commits":6.066666666666666,"dds":"0.27472527472527475","last_synced_commit":"ded9e57f25addb25dcca582115a73a5e80ab2b76"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riscv-rust%2Flongan-nano","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riscv-rust%2Flongan-nano/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riscv-rust%2Flongan-nano/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riscv-rust%2Flongan-nano/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riscv-rust","download_url":"https://codeload.github.com/riscv-rust/longan-nano/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243750478,"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:28.449Z","updated_at":"2025-03-15T15:30:54.213Z","avatar_url":"https://github.com/riscv-rust.png","language":"Rust","funding_links":[],"categories":["Board support crates"],"sub_categories":["Sipeed"],"readme":"[![crates.io](https://img.shields.io/crates/d/longan-nano.svg)](https://crates.io/crates/longan-nano)\n[![crates.io](https://img.shields.io/crates/v/longan-nano.svg)](https://crates.io/crates/longan-nano)\n![Build Status](https://github.com/riscv-rust/longan-nano/workflows/CI/badge.svg)\n\n# `longan-nano`\n\n\u003e Board support crate for the Longan Nano board\n\n## [Documentation](https://docs.rs/crate/longan-nano)\n\n## Getting started\n\n### Installing dependencies\n\n- Rust 1.36 or a newer toolchain. e.g. `rustup default stable`\n\n- `rust-std` components (pre-compiled `core` crate) for the RISC-V target. Run:\n\n``` console\nrustup target add riscv32imac-unknown-none-elf\n```\n\n- RISC-V toolchain ([e.g. from SiFive](https://static.dev.sifive.com/dev-tools/riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14.tar.gz))\n\nOne of:\n\n- [dfu-util](http://dfu-util.sourceforge.net/)\n- [openocd for GD32VF103](https://github.com/riscv-mcu/riscv-openocd)\n- [RV-LINK](https://gitee.com/zoomdy/RV-LINK)\n- [stm32flash](https://sourceforge.net/projects/stm32flash/)\n\nWhen using `dfu-util`, the RISC-V toolchain is not necessary. Only `rust-objcopy` from [cargo-binutils](https://github.com/rust-embedded/cargo-binutils) is needed.\n\nOption B - Install prebuilt toolchain (easier):\n\nFor Ubuntu/Debian:\n```\nsudo apt-get install gcc-riscv64-unknown-elf\n```\n\n### Building \n\nIf you have a GD32VF103C**B** chip on your board, edit `.cargo/config.toml` and replace\n`memory-c8.x` with `memory-cb.x`.\n\nTo build all the provided examples run \n```\ncargo build --examples --release --all-features\n```\n\n### Using dfu-util for Flashing\n\nThe GD32VF103 contains a [DFU](https://www.usb.org/sites/default/files/DFU_1.1.pdf) \ncompatible bootloader which allows to program the firmware of your longan-nano without \nadditional hardware like a JTAG adapter; instead just using an ordenary USB-C cable. \nYou can use [dfu-util](http://dfu-util.sourceforge.net/) or the vendor supplied tool to \nflash the firmware. \n\nUnfortunately, some versions of this chip shipped with a buggy bootloader and it won't report \nthe correct parameters to flash it sucessfully. As of May 2020, the most recent version of \n[dfu-util](http://dfu-util.sourceforge.net/) from the git repository contains a workaround. \nMake sure you use an up-to-date version.\nSee [this issue](https://github.com/riscv-rust/longan-nano/issues/5) for details.\n\nSteps to flash an example via DFU:\n\n1) Extract the binary \n\n```sh\nrust-objcopy -O binary target/riscv32imac-unknown-none-elf/release/examples/blinky firmware.bin\n```\n\nIf using prebuilt toolchain\n```sh\nriscv64-unknown-elf-objcopy -O binary target/riscv32imac-unknown-none-elf/release/blinky firmware.bin\n```\n\n\n2) Flash using `dfu-util`:\n\nKeep the BOOT0 button pressed while power-up or while pressing and releaseing the reset button. Then \nrun \n\n```sh\ndfu-util -a 0 -s 0x08000000:leave -D firmware.bin\n```\n\nEnsure that dfu-util uses a page size of 1024; either because your GD32VF103 has \na bootloader without the the aforementioned bug, or because the output reads\n\n```\n[...]\nDevice returned transfer size 2048\nDfuSe interface name: \"Internal Flash  \"\nFound GD32VF103, which reports a bad page size and count for its internal memory.\nFixed layout based on part number: page size 1024, count 128.\nDownloading to address = 0x08000000, size = 23784\n[...]\n```\n\n### Using OpenOCD for Flashing and Debugging\n\nStart openocd assuming you have Sipeed JTAG adapter:\n```sh\n/path/to/openocd -f sipeed-jtag.cfg -f openocd.cfg\n```\n\nRun one of the examples:\n```sh\ncargo run --example blinky\n```\nor\n```sh\ncargo run --release --example ferris --features lcd\n```\n\n### Using RV-LINK for Flashing and Debugging\n\n[RV-LINK](https://gitee.com/zoomdy/RV-LINK) is a Chinese firmware, similar to\n[Black Magic Probe (BMP)](https://github.com/blacksphere/blackmagic/wiki). It\nsupports the Longan Nano, allowing to use one Longan Nano board as a debug\nprobe for another one. It can be built \u0026 flashed via\n[PlatformIO](https://platformio.org/). Check out the latest version to ensure\nthat the code compiles:\n\n```\n\u003e git clone https://gitee.com/zoomdy/RV-LINK\n\u003e cd RV-LINK\n\u003e git tag \nv0.0.1\nv0.1\nv0.2 # \u003c- seems to be the latest tag, so let's check this out\n\u003e git checkout tags/v0.2 \n```\n\nPlatformIO allows building \u0026 flashing of firmware with a single command. To do\nso, the board needs to be in bootloader mode (DFU mode). The board boots to\nbootloader mode if the bootloader button is pressed while powering it up (e.g.\nby plugging it in). However, it is also possible to enter bootloader mode\nwithout un- and replugging the board: press the boot button, press the reset\nbutton, release the reset button and finally release the boot button while the\nboard is plugged in.\n\n```\n\u003e pio run -t upload # put the board in bootloader mode before\n```\n\nOnce RV-LINK is flashed to your probe, connect the eight debug pins on the\nprobe with the debug pins on the debug target. Ensure that you connect the pins\naccording to this table:\n\n| Probe Pin | Target Pin |\n| ---       | ---        |\n| JTDO      | JTDO       |\n| JTDI      | JTDI       |\n| JTCK      | JTCK       |\n| JTMS      | JTMS       |\n| 3V3       | 3V3        |\n| GND       | GND        |\n\nAfter you connected the debug probe to your host, a new serial port shows up.\nYou can connect GDB to this serial port as an `extended-remote`. For\npredictable behavior when multiple serial devices are present (and hence\n`/dev/ttyACM0` is not necessarily the RV-LINK device),\n[udev](https://www.freedesktop.org/wiki/Software/systemd/) offers id symlinks.\nHowever you may also use `/dev/ttyACM0` or even `COMx` if you run Windows.\n\n```\n\u003e gdb\n(gdb) target extended-remote /dev/serial/by-id/usb-RV-LINK_Longan_Nano_GD32XXX-3.0.0-7z8x9yer-if00\n```\n\nTo flash the firmware, execute `load` in GDB:\n\n```\n\u003e gdb target/remote/debug/demo\n(gdb) target extended-remote /dev/ttyACM0\n(gdb) monitor reset halt\n(gdb) load\n(gdb) monitor reset\n```\n\nTo improve your workflow, you can put the aforementioned GDB commands in\na `debug.gdb` file and add these lines to `.cargo/config.toml`:\n\n```\n[target.riscv32imac-unknown-none-elf]\nrunner = 'gdb -command=debug.gdb'\n```\n\nThis way `cargo run --target riscv32imac-unknown-none-elf` will automatically\nlaunch GDB, flash your firmware on the target and provide you with a full debug\nenvironment.\n\nYou can infer the current status of the board by observing the blinking pattern\nof the green LED:\n\n| Blink Behavior                             | Probe Status                                           |\n| ---                                        | ---                                                    |\n| Short pulse, on for 100ms, off for 900ms   | GDB is not connected                                   |\n| Slow flashing, on for 500ms, off for 500ms | GDB is connected and the debugged MCU is in halt state |\n| Fast blinking, on for 100ms, off for 100ms | GDB is connected, and the debugged MCU is running      |\n| Long pulse, on for 900ms, off for 100ms    | RV-LINK has failed. Retry after resetting RV-LINK      |\n\n\n## Using serial for Flashing\n\nUsing a TTL-to-USB adapter, one can flash the firmware to the device over a serial connection:\n\n```\n$ stm32flash -g 0x08000000 -b 115200 -w firmware.bin /dev/ttyUSB0\n```\n\nwhich sets the base address (`-g 0x08000000`) for the firmware to the start of main flash.\n\nThe baud rate (`-b 115200`), firmware image (`-w firmware.bin`), and serial port (`/dev/ttyUSB0`) are set next.\n\nThe serial port may vary machine to machine, so select the port that makes sense.\n\nMake sure the device is writeable by the current user, or run `stm32flash` as root.\n\n## License\n\nCopyright 2019-2020 [RISC-V team][team]\n\nPermission to use, copy, modify, and/or distribute this software for any purpose\nwith or without fee is hereby granted, provided that the above copyright notice\nand this permission notice appear in all copies.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH\nREGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND\nFITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,\nINDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS\nOF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER\nTORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF\nTHIS SOFTWARE.\n\n## Code of Conduct\n\nContribution to this crate is organized under the terms of the [Rust Code of\nConduct][CoC], the maintainer of this crate, the [RISC-V team][team], promises\nto intervene to uphold that code of conduct.\n\n[CoC]: CODE_OF_CONDUCT.md\n[team]: https://github.com/rust-embedded/wg#the-risc-v-team\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friscv-rust%2Flongan-nano","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friscv-rust%2Flongan-nano","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friscv-rust%2Flongan-nano/lists"}