Skip to content

add details of uHex tool #213

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 11, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion latest-revision/latest-revision-editors.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,9 @@ The latest board revision introduces a superset of the Intel-Hex format that ena
A **Universal Hex** hex file will work on a V1 or V2 board.
A clear indication that you are working with this format is that a compiled .hex file will be ~1.8Mb as opposed to ~700Kb in size.

A [Universal Hex JavaScript Library](https://github.com/microbit-foundation/microbit-universal-hex) has been written to implement the format and associated detailed [specification of the Universal Hex format](https://github.com/microbit-foundation/universal-hex/). Please [get in contact](mailto:support@microbit.org?subject=Request%20for%20access%20to%20Universal%20hex&20spec&body=Name%3A%0D%0A%0D%0AGitHub%20ID%3A) if you require access to the specification.
We have developed a [Universal Hex Creator](../../software/universal-hex-creator) tool, to easily create a .hex file that will support all micro:bit variants.

This tool is based on a [Universal Hex JavaScript Library](https://github.com/microbit-foundation/microbit-universal-hex), written to implement the format and associated detailed [specification of the Universal Hex format](https://github.com/microbit-foundation/universal-hex/). Please [get in contact](mailto:support@microbit.org?subject=Request%20for%20access%20to%20Universal%20hex&20spec&body=Name%3A%0D%0A%0D%0AGitHub%20ID%3A) if you require access to the specification.

### Hex format compatibility

Expand Down
2 changes: 1 addition & 1 deletion latest-revision/latest-revision-main.md
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,7 @@ The editors and apps are compatible with and will let you download and flash a f

More information about this is available on our [hex format](../software/hex-format/#universal-hex-files) page

The Foundation has written a javascript library to generate these files - you do not need to re-implement any file generation.
The Foundation has written a javascript library and [Universal Hex Creator](../software/universal-hex-creator) to generate these files - you do not need to re-implement any file generation.

### Bluetooth BLE

Expand Down
8 changes: 6 additions & 2 deletions software/hex-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,12 @@ A clear indication that you are working with this format is that a compiled .hex

A [Universal Hex JavaScript Library](https://github.com/microbit-foundation/microbit-universal-hex) has been written to implement the format and associated detailed [specification of the Universal Hex format](https://github.com/microbit-foundation/universal-hex/).

## Universal Hex Creator

We have created a [Universal Hex Creator](../universal-hex-creator) tool, to easily create a .hex file that will support all micro:bit variants.

This tool is based on the [Universal Hex JavaScript Library](https://github.com/microbit-foundation/microbit-universal-hex).

### Cross device compatibility

The Universal Hex format has been developed to ensure the best experience for users when moving between board variants. If a V1 only .hex is detected on a V2 board it will throw an error, but a V2 only hex will fail silently on a V1. This is very confusing to users and should be avoided.
Expand All @@ -36,8 +42,6 @@ There may be cases where it is not possible to support both boards, for example

We have created a [standalone error hex](/docs/software/assets/stand-alone-error-v1.hex) that can be combined with a V2 only hex to produce a Hex that will work on a V2 board, but error if used on a V1.

{% include alert-info.html content="We are currently working on a web based and CLI tool to generate Universal Hex files and will publish information on usage here when this is ready. In the meantime, please [get in contact](mailto:support@microbit.org) if you require further information" %}

[Download standalone error hex](/docs/software/assets/stand-alone-error-v1.hex){: .btn.sm-btn download}

This example shows the worst, best and acceptable (when support for V1 is impossible) cases for users. The best case is to provide a Universal Hex that supports all board variants.
Expand Down
17 changes: 17 additions & 0 deletions software/universal-hex-tool.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
layout: page
title: Universal Hex Creator
heading: Universal Hex Creator
description: Create a Universal Hex file
permalink: /software/universal-hex-creator/
ref: universal-hex-tool
lang: en
assigned-to: markw
review-with: carlospa
---

The Universal Hex Creator lets you combine a hex file created for a micro:bit V1 device and a hex file created for a V2 device, resulting in a Universal Hex format that is compatible with all revisions of the micro:bit.

DAPLink will process the Universal Hex and only write data to the relevant board revision; V1 or V2. More information is available on our [Hex format](../hex-format) page and the [Javascript/Typescript libary](https://github.com/microbit-foundation/microbit-universal-hex) on which the Universal Hex Creator tool is based.

{% include uhex-tool.html %}