Create detailed custom-target-porting.md #1145

maclobdell · 2019-08-28T17:51:40Z

Add tutorial about porting Mbed OS to a custom board.

This replaces #1130.

Due to difficulty rebasing the previous PR, I went ahead and created a new one.

I rewrote the document based on feedback received. My goal was to provide more clarity and helpful details.

There might be formatting issues. Pleases review and let me know what I should fix.

maclobdell · 2019-08-29T20:31:51Z

@iriark01 for review

Push up initial copy edits.

iriark01 · 2019-08-30T08:09:51Z

@arekzaluski and @sophewilliams I understand you did a lot of work on this topic - would you like to review this?

AnotherButler · 2019-09-09T21:56:22Z

ping @arekzaluski @sophewilliams

MarceloSalazar · 2019-09-12T13:01:29Z

This doc is really good - what do we need to merge it for 5.14?

iriark01 · 2019-09-12T13:03:37Z

This is still a work in progress and will not make it to 5.14; code freeze has already happened, OOB has started and the release is in six days.

MarceloSalazar · 2019-09-12T13:30:12Z

Note this is not based on any new feature and doesn't depend on OOB. It's based on knowledge gaps we have in our docs.
Maybe could be introduced later after 5.14.0 is released?

iriark01 · 2019-09-19T07:04:41Z

docs/porting/custom-target-porting.md

+
+When designing a custom board based on an existing Mbed Enabled board, you may need to make configuration and software changes to adapt Mbed OS to run on your new board. This is called a software port. The necessary changes may include adaptations for the unique design choices you have made for your new board, such as clocking, pin connections and peripheral usage. This can often be accomplished by adding configuration and source files to an Mbed OS-based application project without the need to modify files within `mbed-os`, itself. If you don't plan to push your changes to the upstream `mbed-os` repository, this simplifies your software configuration management by allowing you to keep your new files separate.
+
+Mbed OS supports target inheritance, which allows you to extend an existing microcontroller (MCU) target and just add software and configurations required for your board. You have the ability to add a file named `custom_target.json` to your project, which can store your custom target configurations without the need to modify `targets.json`.


I'm not clear on the break and order of information in the first two paragraphs.

iriark01 · 2019-09-19T07:05:07Z

docs/porting/custom-target-porting.md

+
+When designing a custom board based on an existing Mbed Enabled board, you may need to make configuration and software changes to adapt Mbed OS to run on your new board. This is called a software port. The necessary changes may include adaptations for the unique design choices you have made for your new board, such as clocking, pin connections and peripheral usage. This can often be accomplished by adding configuration and source files to an Mbed OS-based application project without the need to modify files within `mbed-os`, itself. If you don't plan to push your changes to the upstream `mbed-os` repository, this simplifies your software configuration management by allowing you to keep your new files separate.
+
+Mbed OS supports target inheritance, which allows you to extend an existing microcontroller (MCU) target and just add software and configurations required for your board. You have the ability to add a file named `custom_target.json` to your project, which can store your custom target configurations without the need to modify `targets.json`.


Suggested change

Mbed OS supports target inheritance, which allows you to extend an existing microcontroller (MCU) target and just add software and configurations required for your board. You have the ability to add a file named `custom_target.json` to your project, which can store your custom target configurations without the need to modify `targets.json`.

Mbed OS supports target inheritance, which allows you to extend an existing microcontroller (MCU) target and just add software and configurations required for your board. You can add a file named `custom_target.json` to your project, which can store your custom target configurations without the need to modify `targets.json`.

Note that this sentence assumes I know what targets.json is; might be nice to link to information about it, or any other information we want people to have before they try this tutorial (the assumption may be correct for our readers - I'm just pointing it out)

docs/porting/custom-target-porting.md

iriark01 · 2019-09-19T07:07:10Z

docs/porting/custom-target-porting.md

+
+## Extending an existing MCU target configuration
+
+As an example, consider a situation in which you are creating a new board based on an existing Mbed Enabled board. For this tutorial, consider a new board called `ImaginaryBoard` that is based on [DISCO-L475VG-IOT01A](https://os.mbed.com/platforms/ST-Discovery-L475E-IOT01A/).


Is that an example, or just the premise of this whole document?

iriark01 · 2019-09-19T07:08:10Z

docs/porting/custom-target-porting.md

+
+1. Create a new file named `custom_targets.json` at the same level as the `mbed-os` directory:
+
+   Inspect the contents of `mbed-os/targets/targets.json`. For this example, search for `DISCO_L475VG_IOT01A`.


This feels like a new step.

iriark01 · 2019-09-19T07:23:40Z

docs/porting/custom-target-porting.md

+
+  You can test this simple example using a `DISCO-L475VG-IOT01A`. If you actually created a `ImaginaryBoard` board, you could use that too.  
+
+  <span class="notes">**Note:** Unless your board has an Mbed Enabled debug interface, you need a method of flashing the memory on your board. </span>


Should this come earlier?

iriark01 · 2019-09-19T07:23:51Z

docs/porting/custom-target-porting.md

+
+  <span class="notes">**Note:** Unless your board has an Mbed Enabled debug interface, you need a method of flashing the memory on your board. </span>
+
+  Since the `DISCO-L475VG-IOT01A` has a Mbed Enabled debug interface (STLink in this case), we can use drag-and-drop programming to flash the board.


Suggested change

Since the `DISCO-L475VG-IOT01A` has a Mbed Enabled debug interface (STLink in this case), we can use drag-and-drop programming to flash the board.

Since the `DISCO-L475VG-IOT01A` has an Mbed Enabled debug interface (STLink in this case), we can use drag-and-drop programming to flash the board.

Are we flipping a bit between "We" and "You"?

iriark01 · 2019-09-19T07:24:26Z

docs/porting/custom-target-porting.md

+
+  Locate the binary file and drag it onto the disk drive name for the board (for example, `DIS_L4IOT`).
+
+  After the file transfer is complete, press the reset button on the board. You should see the LED blinking.


Suggested change

After the file transfer is complete, press the reset button on the board. You should see the LED blinking.

When the file transfer is complete, press the reset button on the board. You should see the LED blinking.

iriark01 · 2019-09-19T07:24:50Z

docs/porting/custom-target-porting.md

+
+  After the file transfer is complete, press the reset button on the board. You should see the LED blinking.
+
+1. (Optional) Run automated tests.


Maybe new header?

iriark01 · 2019-09-19T07:25:35Z

docs/porting/custom-target-porting.md

+  mbed test -m IMAGINARYBOARD -t <toolchain>
+  ```
+
+  The tests should start running.


Can we link to some information about testing?

Co-Authored-By: Irit Arkin <[email protected]>

Edit file, mostly for active voice, consistent headings, use of numbered lists and to address comments.

AnotherButler · 2019-11-07T22:00:24Z

@iriark01 Could you please review again?

AnotherButler · 2019-11-07T22:00:47Z

@arekzaluski @sophewilliams Would y'all like to review?

bulislaw

Looks great, I would just add some more details and considerations around the detect code.

bulislaw · 2019-11-11T11:38:40Z

docs/porting/custom-target-porting.md

+#### Changes
+
+1. The board name changed from `DISCO_L475VG_IOT01A` to `IMAGINARYBOARD`, so the board can be uniquely identified.
+1. The `detect_code` changed from `0764` to `1234`. The `detect_code` is a unique number that identifies the board to the Mbed OS test tools. For Mbed Enabled boards, this number is exposed through the debug interface with Mbed CLI by typing `mbedls`.


Do we need some information how to set it? When do you need to get it from us and when it's ok to just pick some? How to avoid clashes? Consideration based on public vs private port? I guess it deserves a link to a separate doc.

Looking through our documentation - I see it mentioned a few times, but never really see it explained well and the terminology is inconsistent.

Sometimes its called a board id (https://www.mbed.com/en/about-mbed/mbed-enabled/requirements/).

Sometimes it is called four-digit hexadecimal identifier (https://os.mbed.com/docs/mbed-os/v5.14/porting/mbed-ls.html)

Sometimes its called a Platform ID (https://github.com/ARMmbed/mbed-os-tools/tree/master/packages/mbed-ls#adding-platform-support).

Sometimes its called unique board ID (https://os.mbed.com/docs/mbed-os/v5.14/porting/setting-up.html)

Sometimes its called detect_code (https://github.com/ARMmbed/mbed-os/blob/master/targets/targets.json)

I like Board ID, but Platform ID or the others seem fine.

For me the key points are:

Board IDs are unique identifiers assigned by the Arm Mbed team.

Board IDs are used by the Mbed tools to identify the connected board.

You really only need your own unique ID if you plan to push your platform to the Mbed community.

You can make Mbed CLI recognize your own custom board even without getting your own Board ID.

Contact a technical account manger or Mbed support if you would like to request a board ID.

@AnotherButler - can you recommend where this information would be best located?

I just added a new commit for this PR with changes related to the Platform ID. Also, I made pull request #1175 to align the terminology and add more detail. Please let me know if this addresses the comments.

AnotherButler · 2019-11-14T22:44:57Z

@maclobdell Can you make these changes requested by @bulislaw ?

AnotherButler · 2019-11-21T20:14:01Z

Thanks for the updates, @maclobdell

This is failing Circle CI because of something unrelated. Could you please rebase, and then I'll merge? If you'd rather, I can close this PR and make these changes directly.

Add content from PR #1145 to fix merge conflict.

AnotherButler · 2019-12-03T17:43:39Z

Closing in favor of 6be8ae4

AnotherButler mentioned this pull request Aug 28, 2019

Create custom-target-porting.md #1130

Closed

add new tutorial, more detailed than previous attempts

d3e07c0

maclobdell force-pushed the add-custom-target-tutorial branch from 852b131 to d3e07c0 Compare August 28, 2019 18:15

Begin edits on custom-target-porting.md

1adde13

Push up initial copy edits.

AnotherButler requested a review from iriark01 August 29, 2019 21:55

AnotherButler requested review from arekzaluski and sophewilliams September 5, 2019 21:38

iriark01 suggested changes Sep 19, 2019

View reviewed changes

Amanda Butler and others added 10 commits October 30, 2019 15:45

Update docs/porting/custom-target-porting.md

938be87

Co-Authored-By: Irit Arkin <[email protected]>

Update docs/porting/custom-target-porting.md

b07cc8f

Co-Authored-By: Irit Arkin <[email protected]>

Update docs/porting/custom-target-porting.md

65ff974

Co-Authored-By: Irit Arkin <[email protected]>

Update docs/porting/custom-target-porting.md

753113a

Co-Authored-By: Irit Arkin <[email protected]>

Update docs/porting/custom-target-porting.md

3d57759

Co-Authored-By: Irit Arkin <[email protected]>

Update docs/porting/custom-target-porting.md

048be6c

Co-Authored-By: Irit Arkin <[email protected]>

Update docs/porting/custom-target-porting.md

8d93db3

Co-Authored-By: Irit Arkin <[email protected]>

Update docs/porting/custom-target-porting.md

3cccc58

Co-Authored-By: Irit Arkin <[email protected]>

rewrites and edits to custom target porting

2f5790d

Edit custom-target-porting.md

dabd879

Edit file, mostly for active voice, consistent headings, use of numbered lists and to address comments.

iriark01 approved these changes Nov 11, 2019

View reviewed changes

bulislaw approved these changes Nov 11, 2019

View reviewed changes

add detect code clarifications

55c5556

AnotherButler pushed a commit that referenced this pull request Dec 3, 2019

Create custom-target-porting.md

6be8ae4

Add content from PR #1145 to fix merge conflict.

AnotherButler closed this Dec 3, 2019

AnotherButler deleted the add-custom-target-tutorial branch December 3, 2019 17:43


		When designing a custom board based on an existing Mbed Enabled board, you may need to make configuration and software changes to adapt Mbed OS to run on your new board. This is called a software port. The necessary changes may include adaptations for the unique design choices you have made for your new board, such as clocking, pin connections and peripheral usage. This can often be accomplished by adding configuration and source files to an Mbed OS-based application project without the need to modify files within `mbed-os`, itself. If you don't plan to push your changes to the upstream `mbed-os` repository, this simplifies your software configuration management by allowing you to keep your new files separate.

		Mbed OS supports target inheritance, which allows you to extend an existing microcontroller (MCU) target and just add software and configurations required for your board. You have the ability to add a file named `custom_target.json` to your project, which can store your custom target configurations without the need to modify `targets.json`.


		## Extending an existing MCU target configuration

		As an example, consider a situation in which you are creating a new board based on an existing Mbed Enabled board. For this tutorial, consider a new board called `ImaginaryBoard` that is based on [DISCO-L475VG-IOT01A](https://os.mbed.com/platforms/ST-Discovery-L475E-IOT01A/).


		1. Create a new file named `custom_targets.json` at the same level as the `mbed-os` directory:

		Inspect the contents of `mbed-os/targets/targets.json`. For this example, search for `DISCO_L475VG_IOT01A`.


		You can test this simple example using a `DISCO-L475VG-IOT01A`. If you actually created a `ImaginaryBoard` board, you could use that too.

		<span class="notes">Note: Unless your board has an Mbed Enabled debug interface, you need a method of flashing the memory on your board. </span>


		<span class="notes">Note: Unless your board has an Mbed Enabled debug interface, you need a method of flashing the memory on your board. </span>

		Since the `DISCO-L475VG-IOT01A` has a Mbed Enabled debug interface (STLink in this case), we can use drag-and-drop programming to flash the board.

	Since the `DISCO-L475VG-IOT01A` has a Mbed Enabled debug interface (STLink in this case), we can use drag-and-drop programming to flash the board.
	Since the `DISCO-L475VG-IOT01A` has an Mbed Enabled debug interface (STLink in this case), we can use drag-and-drop programming to flash the board.


		Locate the binary file and drag it onto the disk drive name for the board (for example, `DIS_L4IOT`).

		After the file transfer is complete, press the reset button on the board. You should see the LED blinking.

	After the file transfer is complete, press the reset button on the board. You should see the LED blinking.
	When the file transfer is complete, press the reset button on the board. You should see the LED blinking.


		After the file transfer is complete, press the reset button on the board. You should see the LED blinking.

		1. (Optional) Run automated tests.

Create detailed custom-target-porting.md #1145

Create detailed custom-target-porting.md #1145

Uh oh!

Conversation

maclobdell commented Aug 28, 2019

Uh oh!

maclobdell commented Aug 29, 2019

Uh oh!

iriark01 commented Aug 30, 2019

Uh oh!

AnotherButler commented Sep 9, 2019

Uh oh!

MarceloSalazar commented Sep 12, 2019

Uh oh!

iriark01 commented Sep 12, 2019

Uh oh!

MarceloSalazar commented Sep 12, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler commented Nov 7, 2019

Uh oh!

AnotherButler commented Nov 7, 2019

Uh oh!

bulislaw left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maclobdell Nov 18, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler commented Nov 14, 2019

Uh oh!

AnotherButler commented Nov 21, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AnotherButler commented Dec 3, 2019

Uh oh!

Uh oh!

maclobdell Nov 18, 2019 •

edited

Loading

AnotherButler commented Nov 21, 2019 •

edited

Loading