Add basic documentation to README

[hannobraun]

Documentation is sorely lacking right now. It would be great to have a more useful README.

[futurepaul]

I'd like to help with this. I have an NRF52840 dev kit that I have built C code for but I don't understand this crate well enough to get the blinky example to work.

If someone can walk me through the setup / build process over discord or something I'd be happy to record that conversation and write it up as documentation! I'm working on a mac but I also have linux and windows available if that's helpful.

[Yatekii]

I can walk you though on IRC, no problem ;) I am there day and night. Just ping me! Mac is great even tho it has nothing to do with this crate ;)

[futurepaul]

Alright thanks to Yatekii I have the blinky example working! (I wasn't converting the binary into a hex before flashing). I'll be happy to write up that process if there's a good place to put it. I'm not familiar enough with the rust embedded world to write docs beyond that, unfortunately.

[hannobraun]

@futurepaul I think it's fine to dump anything that helped you get things working into the README. Not ideal, but anything's better than no documentation, so don't be afraid to propose sub-optimal docs :-)

Another good place for general documentation would be a doc comment in the root module of the respective crate (lib.rs).

[Istar-Eldritch]

I have a nRF52-DK board (nRF52832 Microcontroller). This is how I got it working on debian, it may be used as a starting point.

Dependencies

• arm-none-eabi-objcopy: Required to transform the ELF file to HEX
• nrfjprog: Required to install the HEX in the DK board.

Dependencies for debugging

• openocb compiled with jlink support.
• gdb-multiarch

Debugging

Start openocd

  openocd -f interface/jlink.cfg -c "transport select swd" -f target/nrf52.cfg

Execute the intended example

  cargo run --example <example_name>

Installing

Build the ELF file

  cargo build

Transform the ELF file into HEX

arm-none-eabi-objcopy \
  -O ihex \
  target/thumbv7em-none-eabihf/debug/<name> \
  target/thumbv7em-none-eabihf/debug/<name>.hex

Flash the micro

  nrfjprog --family nRF52 --eraseall && \ 
  nrfjprog --family nRF52 --program target/thumbv7em-none-eabihf/debug/<name>.hex && \
  nrfjprog --family nRF52 -r

Other

.cargo/config

[target.thumbv7em-none-eabihf]
runner = "gdb-multiarch -q -x openocd.gdb"
rustflags = [
  # LLD (shipped with the Rust toolchain) is used as the default linker
  "-C", "link-arg=-Tlink.x",
]

[build]
target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU)

openocb.cfg

# Sample OpenOCD configuration for the STM32F3DISCOVERY development board

# Depending on the hardware revision you got you'll have to pick ONE of these
# interfaces. At any time only one interface should be commented out.

# Revision C (newer revision)
source [find interface/jlink.cfg]

# Revision A and B (older revisions)
# source [find interface/stlink-v2.cfg]

source [find target/nrf52.cfg]

openocb.gdb

target extended-remote :3333

# print demangled symbols
set print asm-demangle on

# set backtrace limit to not have infinite backtrace loops
set backtrace limit 32

# detect unhandled exceptions, hard faults and panics
break DefaultHandler
break HardFault
break rust_begin_unwind

# *try* to stop at the user entry point (it might be gone due to inlining)
break main

monitor arm semihosting enable

# # send captured ITM to the file itm.fifo
# # (the microcontroller SWO pin must be connected to the programmer SWO pin)
# # 8000000 must match the core clock frequency
# monitor tpiu config internal itm.txt uart off 8000000

# # OR: make the microcontroller SWO pin output compatible with UART (8N1)
# # 8000000 must match the core clock frequency
# # 2000000 is the frequency of the SWO pin
# monitor tpiu config external uart off 8000000 2000000

# # enable ITM port 0
# monitor itm port 0 on

load

# start the process but immediately halt the processor
stepi

[simonsso]

Great description!

I was not aware of those options I have always used Segger Ozone to flash the elf file or the builtin flash loader with cp out.hex /media/$USER/JLINK/ - I can't remember if I have replaced the flash loader on with something from segger or if this was the default.

[Istar-Eldritch]

@simonsso As far as I know that is the default behavior. I personally find it easier to just use cargo run though.

[chrysn]

I've created #398 to (at least partially) resolve this issue. Copying the file via USB mass storage is now mentioned; is there any programming method that was previously listed in this thread still relevant enough to include it in that PR?

[jonas-schievink]

Thanks to probe-rs, OpenOCD is now mostly obsolete for flashing and running Rust firmware, so I don't think we need to mention it (and if you have a weird/complicated setup that does require it, you probably know more about how to run firmware on it than we could).

Since #398 now mentions most alternative ways to put firmware on a device that users are likely to need, I think this can be closed.