Debian Codegraph @

ports/stm32/boards/LEGO_HUB_NO7/README.md

raw
1 LEGO Hub No.7
2 =============
3
4 This board definition is for the LEGO Hub No. 7, a LEGO control unit with 1 button,
5 2 RGB LEDs, 2 Powered Up ports, 6-DOF sensor, Bluetooth, USB, 4MiB external SPI
6 flash storage, and a rechargeable battery.
7
8 Features that are currently supported:
9 - standard MicroPython
10 - machine and bluetooth modules
11 - filesystem
12 - USB VCP, MSC and HID
13
14 The Hub has a bootloader preinstalled at 0x08000000 (which is 32kiB in size) which
15 cannot be erased. This bootloader is entered by holding down the button for 5 seconds,
16 at which point the USB DFU device appears. If the battery is installed then the
17 RGB LED will flash purple. If the battery is not installed, the LED will flash orange
18 briefly and then the hub will turn off (so having the battery installed is required).
19 When this bootloader is active, the flash from 0x08008000 and up can be erased
20 and programmed via USB DFU.
21
22 The built-in bootloader has some drawbacks: it cannot be entered programmatically,
23 and it does not keep the Hub powered up when running from battery (which requires
24 keeping BAT_PWR_EN high). As such, this board is configured to work with mboot as
25 a secondary bootloader: mboot is placed at 0x08008000 and the main application
26 firmware at 0x08010000. When mboot is installed it can be entered programmatically
27 via machine.bootloader().
28
29 Backing up original Hub firmware
30 --------------------------------
31
32 Before installing MicroPython it is advised to backup the original LEGO firmware that
33 the Hub comes installed with. To do this, enter the built-in bootloader by holding
34 down the power button for 5 seconds while powering up the Hub via USB (you may
35 need to take out the battery and disconnect USB to power off the Hub first). Then
36 run the following command from the root of this repository:
37
38 $ cd ports/stm32
39 $ make BOARD=LEGO_HUB_NO7 backup-hub-firmware
40
41 This will create a file called `lego_hub_firmware.dfu`. Put this file in a safe
42 location. To restore it, enter the built-in bootloader again and run:
43
44 $ make BOARD=LEGO_HUB_NO7 restore-hub-firmware
45
46 This will restore the original firmware but not the filesystem. To recreate the
47 original filesystem the Hub must be updated using the appropriate LEGO PC
48 application.
49
50 Installing MicroPython
51 ----------------------
52
53 You first need to build and install mboot, which only needs to be done once. From
54 the root of this repository run:
55
56 $ cd ports/stm32/mboot
57 $ make BOARD=LEGO_HUB_NO7
58
59 Now enter the built-in bootloader by holding down the power button for 5
60 seconds while powering up the Hub via USB (you may need to take out the battery
61 and disconnect USB to power off the Hub first). Then run:
62
63 $ make BOARD=LEGO_HUB_NO7 deploy
64
65 mboot should now be installed. To enter mboot, remove USB and the battery.
66 Connect the USB cable (the other end of the USB cable must be connected to
67 something that provides power). The status light should start cycling through
68 different colors. Replace the battery (the button will not work without the
69 battery present). Press the button to activate the desired boot mode:
70
71 - Status light is red - run application (normal boot).
72 - Status light is green - run application in factory file system mode.
73 - Status light is blue - run application in safe mode.
74 - Status light is white - start DFU on the USB port.
75
76
77 Now build MicroPython (start at the root of this repository):
78
79 $ cd mpy-cross
80 $ make
81 $ cd ../ports/stm32
82 $ make submodules
83 $ make BOARD=LEGO_HUB_NO7
84
85 And deploy to the Hub (making sure mboot DFU is active, the center button is
86 blinking red):
87
88 $ make BOARD=LEGO_HUB_NO7 deploy
89
90 If successful, the Hub should now appear as a USB serial and mass storage device.
91
92 Using MicroPython on the Hub
93 ----------------------------
94
95 Access the MicroPython REPL using mpremote (pip install mpremote), or with any
96 serial terminal program.
97
98 To scan for BLE devices:
99
100 >>> import bluetooth
101 >>> ble = bluetooth.BLE()
102 >>> ble.irq(lambda *x: print(*x))
103 >>> ble.active(1)
104 >>> ble.gap_scan(2000, 625, 625)
105
106 Use help("modules") to see available built-in modules.
107
108 Updating MicroPython from the Hub's filesystem
109 ----------------------------------------------
110
111 You can update the MicroPython application firmware using the instructions above
112 for installing the firmware for the first time. The Hub also supports updating
113 the application firmware from within MicroPython itself, using the on-board
114 filesystem.
115
116 To use this feature, build the firmware (see above for details) then gzip it and
117 copy the resulting file to the Hub (eg using mpremote):
118
119 $ make BOARD=LEGO_HUB_NO7
120 $ gzip build-LEGO_HUB_NO7/firmware.dfu
121 $ mpremote cp build-LEGO_HUB_NO7/firmware.dfu.gz :
122
123 Then get a REPL on the Hub and execute:
124
125 >>> import appupdate
126 >>> appupdate.update_app("firmware.dfu.gz")
127
128 You can alternatively run this REPL command using mpremote:
129
130 $ mpremote exec --no-follow "import appupdate; appupdate.update_app('firmware.dfu.gz')"
131
132 At that point the Hub should restart and the LED on the central button will flash
133 different colours. Once the update is complete the LED will stop flashing and the
134 Hub will appear again as a USB device. The application firmware is now updated
135 and you can remove the firmware.dfu.gz file if desired.