Repository files navigation

A template for building applications for TI MSP430 microcontrollers.

This project is developed and maintained by theMSP430 team.

• Rust nightly-2022-01-24 or a newer toolchain.Only nightly compilers workfor now.

  Therust-toolchain.toml file makes sure this stepis done for you. This file tellsrustup to downloadand use nightly compiler for this crate, as well as download the compilersource to buildlibcore.

  You can manually set up a nightly compiler as the default for all MSP430projects by running:

  $rustup default nightly$rustup component add rust-src

  Alternatively, you can manually set up overrides on a project basis using:

  $rustup overrideset --path /path/to/crate nightly-YYYY-MM-DD`.$rustup component add --toolchain nightly-YYYY-MM-DD rust-src

• Thecargo generate subcommand (Installation instructions).

• TI'sMSP430 GCC Compiler,version 8.3.0 or greater.msp430-elf-gcc should be visible on the path.

The following dependencies are required in order to generate a peripheral access crate (seeUsing this template below)

• svd2rust, version 0.20.0 ora newer commit.

• msp430_svd, version 0.3.0 or anewer commit. Cloning the repo and following the directions in README.md issufficient.

0. Before instantiating a project, you need to know some characteristics aboutyour specific MSP430 device that will be used to fill in the template. Inparticular:

   • What is the exact part number of your device? Which MSP430 family doesyour part belong to?

   • Does your part have an already-existingperipheral access crate (PAC)?

   • How much flash memory, RAM, and how many interrupt vectors does yourdevice have?

   • Where does flash memory, RAM, and interrupt vectors begin in the addressspace?

   msp430g2553 is used for the examples in this crate. Answering the firstquestion above:

   • msp430g2553 belongs to theMSP430x2xx family.

   The linked family manual anddatasheetcan be used to answer the remaining questions:

   • Themsp430g2553 PAC exists already and can be found oncrates.io.

   • msp430g2553 has 16kB of flash memory, 512 bytes of RAM, and 16 vectors.

   • Flash memory begins at address 0xC000. RAM begins at address 0x0200.The interrupt vectors begin at 0xFFE0.

1. If your particular device does not have a PAC crate, you will need togenerate one usingsvd2rust and possiblypublishthe crate tohttps://crates.io. To generate an SVD file, follow the directionsin themsp430_svdREADME.mdfor your device.

   In some cases likemsp430fr2355,TI's linker files are not consistent with datasheets on where interruptvectors begin and how many interrupt vectors there are for a given device.In case of a conflict,examinethe linker script to determine where to start theVECTORS section inmemory.x. Copies of many linker scripts are kept in themsp430_svdrepository.

2. Instantiate the template and follow the prompts.

   $cargo generate --git https://github.com/rust-embedded/msp430-quickstartProject Name: appCreating project called `app`...Done! New project created /tmp/app$cd app

3. If not targetingmsp430g2553, replace the PAC entry formsp430g2553 inCargo.toml with that of your device, e.g.:

   # [dependencies.msp430g2553]# version = "0.3.0"# features = ["rt"][dependencies.msp430fr2355]version ="0.4.0"features = ["rt"]

4. Populate thememory.x file with address space layout information of yourdevice.Note: As mentioned above, in case of a conflict between thedatasheet and linker script on where interrupt vectors begin, use thelinker script!

   $cat memory.xMEMORY{  /* These values are correct for the msp430g2553 device. You will need to     modify these values if using a different device. Room must be reserved     for interrupt vectors plus reset vector and the end of the first 64kB     of address space. */  RAM : ORIGIN = 0x0200, LENGTH = 0x0200  ROM : ORIGIN = 0xC000, LENGTH = 0x3FE0  VECTORS : ORIGIN = 0xFFE0, LENGTH = 0x20}

5. Build the template application or one of the examples. Some examples(such astimer ortemp-hal) may not compile due to sizeconstraints when building using thedev profile (the default). Pass the--release option tocargo build in these cases.

   $cargo build$cargo build --examples

   Note that due to.cargo/config andrust-toolchain.toml,the above is shorthand for:

   $cargo +nightly build --target=msp430-none-elf -Zbuild-std=core$cargo +nightly build --target=msp430-none-elf -Zbuild-std=core --examples

   You may wish to experiment with other commented options in.cargo/config.

6. Once you have an ELF binary built, flash it to your microcontroller. Usemspdebug to launch a debug session andmsp430-elf-gdb with the linked gdb script. For the msp430g2553 and the MSP-EXP430G2 launchpad board this looks like the following:

   In one terminal session

   $mspdebug -C mspdebug.cfg rf2500

   In another terminal session

   $msp430-elf-gdb -x mspdebug.gdb target/msp430-none-elf/debug/app

   This will flash your Rust code to the microcontroller and open a gdb debugging session to step through it.

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)

• MIT license (LICENSE-MIT orhttp://opensource.org/licenses/MIT)at your option.

Unless you explicitly state otherwise, any contribution intentionally submittedfor inclusion in the work by you, as defined in the Apache-2.0 license, shall bedual licensed as above, without any additional terms or conditions.