Wunderbar upgrade to Conrad Connect firmware and onboarding manual

Transcription

1 Wunderbar upgrade to Conrad Connect firmware and onboarding manual Conrad Electronic SE Page 1 of 28

2 Contents 1 Outline 3 2 Firmware upgrade Windows Upgrade procedure Linux and macos Upgrade procedure Firmware update Update procedure Onboarding Prerequisites Onboarding procedure Buttons & led indications Reset button User button Button combination User led WiFi led Power led Page 2 of 28

3 1 Outline This document contains instructions on upgrading existing Wunderbar firmware to V2 version, describes onboarding procedure for this new firmware and explains buttons functionality and led indications. Page 3 of 28

4 2 Firmware upgrade Wunderbar can connect to Conrad Connect once the firmware is upgraded to V2 version. This process needs to be performed only once. 2.1 Windows Two programs are required during firmware upgrade procedure: 1. Zadig [link] Automated Driver Installer GUI application which helps installing correct USB drivers for Wunderbar 2. dfu-util [link] which is used to update firmware on Wunderbar Upgrade procedure 1. Download and unpack dfu-util [link] to a folder on your computer. In this example C:\wunderbar will be used. Figure 1: Folder with dfu-util unpacked 2. Download firmware upgrade package from Conrad [link] and unpack it to the same folder as dfu-util. Page 4 of 28

5 Figure 2: Folder with dfu-util and firmware upgrade package 3. Connect Li-Ion Battery to Wunderbar board. Note! Battery is crucial for proper Wunderbar operation and is required even when Wunderbar is connected to USB port! 4. Connect Wunderbar to computer with USB Micro cable. If Windows starts automatic driver installation it can be safely ignored. Page 5 of 28

6 Figure 3: Windows 10 automatic driver installation pop-up Note! Please use USB cable bundled with Wunderbar. Not all USB cables are wired correctly and Wunderbar might not be correctly recognized by your computer. 5. Put Wunderbar into firmware update mode: (a) press and hold User button (figure 4) (b) press and release Reset button (figure 4) (c) release User button Power led and User led should be on. Reset button User button WiFi led User led Power led Figure 4: Wunderbar master module buttons and leds Page 6 of 28

7 6. Download Zadig [link] and unpack it to same folder as dfu-util. Figure 5: Folder with dfu-util, firmware upgrade package and Zadig 7. Start Zadig application. If Zadig list is empty: Refresh the list by clicking on List All Devices in Options menu Page 7 of 28

8 Wunderbar should now be selectable from drop down list 8. Before clicking on Install Driver (or Replace Driver ) button make sure that WinUSB driver is selected: 9. Once Install Driver button is clicked Zadig will begin driver installation which should finish shortly with following message Page 8 of 28

9 10. Unplug Wunderbar from USB port and plug it again to force Windows to use new drivers. 11. Put Wunderbar into firmware update mode: (a) Press and hold User button (figure 4) (b) Press and release Reset button (figure 4) (c) release User button 12. Click on Windows start button and type Device Manager (in German Windows version please type Geräte-Manager ) 13. Wunderbar will be visible as WunderBar firmware update device under Universal Serial Bus devices Page 9 of 28

10 14. Click on Windows start button and type cmd to start Command Prompt 15. In Command Prompt navigate to folder with dfu-util, firmware upgrade package and Zadig, by typing: cd C:\wunderbar Page 10 of 28

11 16. Verify that Wunderbar is visible by dfu-util by typing: dfu-util.exe -l Output will look similar to this: 17. Now, upgrade Wunderbar with Bluetooth upgrader: dfu-util.exe -d 15a2:1000 -a 0 -D wunderbar_ble_updater.bin Output will look similar to this: Page 11 of 28

12 18. Restart Wunderbar with Reset button 19. A new removable drive, named WUNDERBAR, should appear on your computer after a few seconds. There will be two files on this drive: 20. Copy wunderbar master ble.hex to this new drive (drag & drop works!) 21. The drive will disappear after the file is completely copied. Warning about improperly ejected drive can be ignored. 22. After few seconds the same drive will appear again and should contain only following 2 files: Page 12 of 28

13 Any other file will mean that update failed. You can open FAIL.TXT or ASSERT.TXT to check exact error message. 23. Put Wunderbar into firmware update again (like in step 5) 24. Verify again that Wunderbar is in firmware update mode and available to dfu-util (like in step 16) 25. Upgrade Wunderbar with latest firmware: dfu-util.exe -d 15a2:1000 -a 0 -D wunderbar_v2.bin Output will look similar to this: 26. Finally restart Wunderbar with Reset button. User led should start blinking, indicating that Wunderbar is ready for onboarding. That completes firmware upgrade procedure. Freshly upgraded Wunderbar has latest V2 firmware and can be onboarded as described in chapter 4. Page 13 of 28

14 2.2 Linux and macos Original Wunderbar firmware contains a bootloader that can be used to program Wunderbar with new software. A program called dfu-util is required for this procedure. Latest dfu-util version can be installed on: Ubuntu Linux $ apt-get install dfu-util macos $ brew install dfu-util Upgrade procedure 1. Download firmware upgrade package from Conrad [link] and unpack it 2. Connect Li-Ion Battery to Wunderbar board. Note! Battery is crucial for proper Wunderbar operation and is required even when Wunderbar is connected to USB port! 3. Connect Wunderbar to computer with USB Micro cable. Page 14 of 28

15 Note! Please use USB cable bundled with Wunderbar. Not all USB cables are wired correctly and Wunderbar might not be properly recognized by your computer. 4. Put Wunderbar into firmware update mode: (a) press and hold User button (figure 6) (b) press and release Reset button (figure 6) (c) release User button Power led and User led on master module should be on. Reset button User button WiFi led User led Power led Figure 6: Wunderbar master module buttons and leds 5. Verify that Wunderbar is visible by dfu-util by executing following command: $ dfu-util -l Page 15 of 28

16 Output should be similar (dfu-util version and serial number might differ) to this: dfu-util 0.9 Copyright Weston Schmidt, Harald Welte and OpenMoko Inc. Copyright Tormod Volden and Stefan Schmidt This program is Free Software and has ABSOLUTELY NO WARRANTY Please report bugs to Found DFU: [15a2:1000] ver=0000, devnum=22, cfg=1, intf=0, path=" ", alt=0, name="unknown", serial="ffffffff4e " 6. Now, upgrade Wunderbar with Bluetooth upgrader: $ dfu-util -d 15a2:1000 -a 0 -D /firmware/path/wunderbar_ble_updater.bin Successful execution should produce following output: dfu-util 0.9 Copyright Weston Schmidt, Harald Welte and OpenMoko Inc. Copyright Tormod Volden and Stefan Schmidt This program is Free Software and has ABSOLUTELY NO WARRANTY Please report bugs to dfu-util: Invalid DFU suffix signature dfu-util: A valid DFU suffix will be required in a future dfu-util release!!! Deducing device DFU version from functional descriptor length Opening DFU capable USB device... ID 15a2:1000 Run-time device DFU version 0110 Claiming USB DFU Interface... Setting Alternate Setting #0... Determining device status: state = dfuidle, status = 0 dfuidle, continuing DFU mode device DFU version 0110 Device returned transfer size 4096 Copying data from PC to DFU device Download [=========================] 100% bytes Download done. state(2) = dfuidle, status(0) = No error condition is present Done! 7. Restart Wunderbar with Reset button once the upgrade is complete 8. A new removable drive, named WUNDERBAR, should appear on your computer after a few seconds. There will be two files on this drive: Page 16 of 28

17 (a) CONRAD.HTM (b) DETAILS.TXT 9. Copy wunderbar master ble.hex to this new drive 10. The drive will disappear after few seconds. Warning about improperly ejected drive can be ignored. 11. After few more seconds the same drive will appear again and should contain only following 2 files: (a) CONRAD.HTM (b) DETAILS.TXT Any other file will mean that update failed. You can open FAIL.TXT or ASSERT.TXT to check exact error message. 12. Put Wunderbar into firmware update again (like in step 4) 13. Verify again that Wunderbar is in firmware update mode and available to dfu-util (like in step 5) 14. Upgrade Wunderbar with latest firmware: $ dfu-util -d 15a2:1000 -a 0 -D /firmware/path/wunderbar_v2.bin 15. Finally restart Wunderbar as shown in step 7. User led should start blinking, indicating that Wunderbar is ready for onboarding. That completes firmware upgrading procedure. Freshly upgraded Wunderbar has latest V2 firmware can be onboarded as described in chapter 4. Page 17 of 28

18 3 Firmware update Wunderbar firmware can be updated or replaced with custom one via DFU bootloader. It is recommended to update V2 firmware to the latest revision available. You can get the version of firmware running on your Wunderbar and check if it is the latest available, by logging in to Conrad Connect dashboard [link] and navigating to your Wunderbar. 3.1 Update procedure To start an update simply put Wunderbar into DFU mode: 1. press and hold User button (figure 11) 2. press and release Reset button (figure 11) 3. release User button Then, verify that Wunderbar entered bootloader: 1. User led is constantly on 2. following command $ dfu-util -l returns similar output: dfu-util 0.9 Copyright Weston Schmidt, Harald Welte and OpenMoko Inc. Copyright Tormod Volden and Stefan Schmidt This program is Free Software and has ABSOLUTELY NO WARRANTY Please report bugs to Found DFU: [15a2:1000] ver=0000, devnum=22, cfg=1, intf=0, path=" ", alt=0, name="unknown", serial="ffffffff4e " Wunderbar firmware can now be updated with following command: $ dfu-util -d 15a2:1000 -a 0 -D new_firmware.bin new firmware.bin should be changed to path and name of new firmware binary that you want to put on Wunderbar. Page 18 of 28

19 Note! It is recommended to re-onboard Wunderbar after Wunderbar V2 firmware update! Warning! Custom firmware only! Custom firmware must be linked properly - application has to start at address 0x , otherwise bootloader can get corrupted! Page 19 of 28

20 4 Onboarding 4.1 Prerequisites Wunderbar V2 firmware provides an onboarding method through USB. Communication with Wunderbar is done over virtual com port, so a terminal application is required. CoolTerm [link] is a free tool, recommended on all operating systems and the following instruction will assume that this app is used. Note! CoolTerm does not handle backspace key by default, so it is highly recommended to enable this support in Options -> Terminal before onboarding. Figure 7: Option to enable proper backspace handling 4.2 Onboarding procedure 1. Create new Wunderbar device on ConradConnect [link], generate and write down the short token and device name. 2. Connect Li-Ion Battery to Wunderbar board Page 20 of 28

21 3. Connect Wunderbar to computer with USB Micro cable. Note! Please use USB cable bundled with Wunderbar. Not all USB cables are wired correctly and Wunderbar might not be correctly recognized by your computer. 4. On Windows, COM port number needed for next step can be found in Device Manager. (a) Click on Windows start button and type Device Manager (in German Windows version please type Geräte-Manager ) Page 21 of 28

22 (b) Wunderbar will be visible as WUNDERBAR V2 CDCVCOM or USB Serial Device (COMX) device under Ports (COM & LPT) Number after COM in brackets indicate port number and this name should be used in CoolTerm when selecting port. 5. Open CoolTerm app and configure serial port and baudrate as shown on figure 8. Baudrate should be set , name of serial port will differ on each computer and system. On Windows it should be COMX (where X is a number) and on Linux/macOS it should be similar to the figure. Page 22 of 28

23 Figure 8: Serial port settings 6. Once configuration is accepted you can click on Connect button. Figure 9 7. Following text should appear in the console: Welcome to WunderBar V2 onboarding wizard! This app will guide you through the process of onboarding your device. Press ENTER to continue. After hitting enter onboarding wizard will start and ask you for your: Page 23 of 28

24 (a) WiFi SSID (b) Security type (open network, WEP, WPA, WPA2) (c) WiFi password (d) ConradConnect login name (e) Short token generated in step 1 on ConradConnect [link] (f) Device name generated in step 1 on ConradConnect [link] During onboarding you will also be asked to put all sensors into onboarding mode, by clicking on the button on sensor boards (10). Figure Depending on your WiFi network and internet connection onboarding process might take a minute or two. Once Wunderbar successfully publishes message to MQTT broker a following message will appear in the console: MQTT connected to mqtt.cdc.conradconnect.de:8883 From this point on your Wunderbar is fully configured and sending data to ConradConnect. Page 24 of 28

25 Wunderbar configuration, like WiFi SSID, password or Conrad Connect credentials, can be changed by running onboarding process again. In order to enter onboarding mode long press (over 5 seconds, till User led is blinking rapidly) User button when Wunderbar is running. Page 25 of 28

26 5 Buttons & led indications Reset button User button WiFi led User led Power led Figure 11: Wunderbar master module buttons and leds 5.1 Reset button This button has single functionality to force reset Wunderbar at any time. Press and release of Reset button alone will always result in Wunderbar restarting in application mode, as length of this button press is not monitored. Warning! It is not recommended to reset Wunderbar at the end of onboarding process, while Wunderbar is storing data, as it might lead to data corruption and/or render Wunderbar nonfunctional. 5.2 User button User button has two functions: Page 26 of 28

27 1. Long press (over 5 seconds): this will clear onboarding data from Wunderbar. Once this button is pressed for 5 seconds User led will start blinking rapidly and onboarding data will be cleared when button is released. This is required if Wunderbar configuration (WiFi or Conrad Connect credentials) needs to be changed. Warning! It is not recommended to clear onboarding data at the end of onboarding process, while Wunderbar is storing data, as it might lead to data corruption and/or render Wunderbar nonfunctional. 2. Short press (under 5 seconds): if Wunderbar is onboarded this will send a message to Conrad Connect Cloud with a counter of button presses. Otherwise, short press on User button has no effect. 5.3 Button combination Wunderbar has a special firmware upgrade mode, where it is possible to change Wunderbar s firmware. To enter this mode (called DFU mode): press and hold User button press and release Reset button release User button Warning! Wunderbar operation mode can be changed at any time, though it is not recommended to switch mode at the end of onboarding process and not to press both buttons longer than 5 seconds to avoid data and/or hardware corruption. 5.4 User led User led is the main feedback mechanism for Wunderbar. It has following indications: Slow blinking (every 0.45 second) indicates that Wunderbar is connecting to WiFi. Normal blinking (every 0.3 second) indicates that Wunderbar is not onboarded and awaits connection over serial port. Page 27 of 28

28 Fast blinking (every 0.13 second) indicates that Wunderbar is initiating communication with Conrad Connect. Rapid blinking (every 30 millisecond) indicates that Wunderbar is primed for clearing onboarding data; this patter will appear only after holding User button pressed for more than 5 seconds. Repeated 5 short and 5 longer blinks indicates that Wunderbar experienced a fatal error and has to be restarted with Reset button. Toggling on keyboard input - during onboarding process User led will toggle on every character entry on serial port. Note! If Wunderbar is onboarded User led status can be controlled from Conrad Connect and this may interfere with any indication (apart from fatal error)! 5.5 WiFi led Wifi led is on when Wunderbar is successfully connected to WiFi network, otherwise it is off. 5.6 Power led Power led is on when Wunderbar is connected to USB port and the battery is charging, otherwise it is off. Page 28 of 28