pic32prog: add a documentation on how to update PICkit3 by cladmi · Pull Request #9260 · RIOT-OS/RIOT

cladmi · 2018-05-31T15:32:21Z

Contribution description

To use pic32prog, the PICkit3 must be updated with a scripting mode firmware.
This describes how to do it on Linux using a windows VM (free).

I did what was described here: #6092 (comment)

Future work

replayed on other computers (also on mac)
Adapted to be parsed by doxygen and maybe also in line with the boards documentation migration.
Maybe add information for PICkit2 no idea how it works

Issues/PRs references

#6092 (comment)
Documents #9259

miri64 · 2018-06-05T13:51:06Z

dist/tools/pic32prog/doc.md

+Flashing on Linux using pickit-3
+================================
+
+Allow flashing a pic32-wifire from linux using https://github.com/sergev/pic32prog


Who allows that?

Hmm... yeah, maybe this needs a rewording, or just remove "Allow".

Flashing another firmware on the pickit-3 allows that.
I could go for "Update the pickit-3 firmware to allow flashing..."

I think it would be better to have something a little more descriptive. E.g. "Go to https://github.com/sergev/pic32prog and download the PIC32 programmer software"?

(+ build it using make)

It will be automatically built by the RIOT build system (like edbg).

Ahhhh, now I understand the sentence.... the link isn't supposed to be followed, but just used as a noun here... Ok... then maybe use some markdown magic here instead ;-):

This document describes how to enable flashing a pic32-wifire from linux using [pic32prog] with a PICkit-3  [pic32prog]: https://github.com/sergev/pic32prog

miri64 · 2018-06-05T13:51:21Z

dist/tools/pic32prog/doc.md

+
+### Setup Windows VM
+
+You can download a free 90 days valid windows virtualbox image from:


Why do I need to download it?

That's only if you need to change the firmware of your pickit3 (usually you'll need), and it can only be done under windows.

I know this, but it isn't clear from this document.

I could add a global summary at the beginning explaining what should be done and how:

Update pickit-3 firmware to allow flashing from linux

Updating the firmware should be done from a windows computer

This tutorial will explain how to do it from a virtual machine.

I do net think it would then be necessary to repeat it after if explained at the beginning.

miri64

Some initial comments while trying out the process (won't finish today).

miri64 · 2018-06-11T13:38:30Z

dist/tools/pic32prog/doc.md

+* optional: set an empty password in Settings-Accounts
+* optional: Create a shared folder with your host machine. I run an offline
+  windows machine so download everything from my host.
+* Install Virtualbox Guest-additions for USB support (reboot)


I think this could need some details. I know how to do that, but someone who never worked with VirtualBox (or VMs in general) might not know what to do here.

miri64 · 2018-06-11T13:38:37Z

dist/tools/pic32prog/doc.md

+* optional: Create a shared folder with your host machine. I run an offline
+  windows machine so download everything from my host.
+* Install Virtualbox Guest-additions for USB support (reboot)
+* USB add both 'microchip' usb as USB1 devices


I think this could need some details. I know how to do that, but someone who never worked with VirtualBox (or VMs in general) might not know what to do here.

miri64 · 2018-06-11T13:38:43Z

dist/tools/pic32prog/doc.md

+  * optional: disabled network
+* Start and login with password: Passw0rd!
+* optional: set an empty password in Settings-Accounts
+* optional: Create a shared folder with your host machine. I run an offline


I think this could need some details. I know how to do that, but someone who never worked with VirtualBox (or VMs in general) might not know what to do here.

miri64 · 2018-06-11T13:39:16Z

dist/tools/pic32prog/doc.md

+
+* Create a machine in virtualbox in File-Import Appliance.
+  * optional: disabled network
+* Start and login with password: Passw0rd!


My VM (MSEdge - Win10.ova) started without password prompt.

Ok I will remove it. It is explained on the microsoft page anyway.

miri64 · 2018-06-11T13:39:30Z

dist/tools/pic32prog/doc.md

+I downloaded a Windows 10 virtualbox image
+
+* Create a machine in virtualbox in File-Import Appliance.
+  * optional: disabled network


I think this could need some details. I know how to do that, but someone who never worked with VirtualBox (or VMs in general) might not know what to do here.

I will remove the parts about networking and shared folder as these are just because it is not required to connect your windows to the internet and that I tend to not connect them without antivirus but it should not be the problem of the tutorial.

miri64 · 2018-06-11T13:42:52Z

dist/tools/pic32prog/doc.md

+* optional: Create a shared folder with your host machine. I run an offline
+  windows machine so download everything from my host.
+* Install Virtualbox Guest-additions for USB support (reboot)
+* USB add both 'microchip' usb as USB1 devices


It's unclear here, that this enabling USB is only possible, when the machine is shut down.

miri64 · 2018-06-11T13:55:42Z

dist/tools/pic32prog/doc.md

+* Run `setup.exe`
+* Run PICkit3
+* Tools/Download PICkit Operating System
+  * Select c://Program Files/Microchip/PICkit3/PK3OSV020005.hex


The application seems to stall during this process.

It should be fixed by permanently registering the usb device to auto-reattach it.

miri64 · 2018-06-11T13:56:38Z

dist/tools/pic32prog/doc.md

+* Connect the chipKIT-Wi-Fire to USB
+* Connect the PICkit3 to JP1 ICSP holes
+  * https://docs.creatordev.io/wifire/guides/wifire-programming/
+  * The Arrow `▶` goes into the hole number 1 (a hole with a square around it)


Hole? You probably mean port or pin ;-).

miri64 · 2018-06-11T14:02:13Z

dist/tools/pic32prog/doc.md

+* Tools/Download PICkit Operating System
+  * Select c://Program Files/Microchip/PICkit3/PK3OSV020005.hex
+* Device should be flashed there will be a message saying the board is found
+* Turn off your VM


The application is crashing when exiting. Maybe calm the reader down, that this is "normal" ;-).

miri64 · 2018-06-11T14:08:01Z

dist/tools/pic32prog/doc.md

+Programmer for Microchip PIC32 microcontrollers, Version 2.0.221
+    Copyright: (C) 2011-2015 Serge Vakulenko
+      Adapter: PICkit3 Version 2.0.5
+    Processor: MZ2048EFG100 (id 1720E053)


I still get No target found. here :-(

It was a permissions problem after all. Maybe also add a line above that the udev rules need to be adapted:

ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="900a", MODE="664", GROUP="plugdev

cladmi · 2018-06-12T14:36:37Z

@miri64 Thank you for the thorough review. I tried to address all your comments in separate commits.

miri64

Some minor stuff left.

miri64 · 2018-06-13T11:27:36Z

dist/tools/pic32prog/doc.md

+* Shutdown the virtual machine
+* In the virtual machine settings, go to USB:
+  * Select "Enable USB Controller" with "USB 1.1"
+  * Click the small '+' sign on the right and add the Microchip devices.


(The device needs to be plugged in for this)

miri64 · 2018-06-13T11:30:37Z

dist/tools/pic32prog/doc.md

+permission issue.
+
+Add yourself to the `plugdev` group, add the following `udev` rule and reboot.
+(Find a tutorial if you do not know how to do this).


RTFM is not very friendly. Especially since explaining that you need to add the rule to a file in /etc/udev/rules.d is just as short ;-)

Yeaaaaahhh you are right.

I checked my files and found that I had mplab udev rules, that is why it was detected on my computer.

They had some wildcard values for idProduct and found this other website talking about rules for these devices: http://en.microstickplus.com/mplabx-on-linux
So I put the link and only use idVendor as selection.

miri64 · 2018-06-15T14:40:53Z

I guess adding the binary file dist/tools/pic32prog/pic32prog in the last commit wasn't your intention ;-)

miri64

Some minor nits, some stuff that still isn't quite ironed out, but overall I think if this is fixed (and the binary file removed), we can merge.

miri64 · 2018-06-15T14:43:15Z

dist/tools/pic32prog/doc.md

+
+It will require flashing a specific firmware on the PICkit3.
+As this can only be done from a Windows computer, that not many Linux users
+have, the following steps explain how to setup a Windows VirtualBox virtual


This document contains several spellings of VirtualBox (capitalization differs). Please decide on one (I prefer the canonical spelling).

Updated all to VirtualBox.

miri64 · 2018-06-15T14:44:24Z

dist/tools/pic32prog/doc.md

+
+* Install Virtualbox
+* Add yourself to the 'vboxusers' group
+  `sudo usermod -a -G vboxusers your_username`


Rendered this looks a little bit weird due to the missing newline.

miri64 · 2018-06-15T14:45:41Z

dist/tools/pic32prog/doc.md

+
+* PICkit3-Programmer http://ww1.microchip.com/downloads/en/DeviceDoc/PICkit3%20Programmer%20Application%20v3.10.zip
+
+Adapted from the README (on Windows 10 machine .NET 4.00 is already installed)


The context of this sentence isn't clear to me (maybe because it is missing a subject or a colon at the end?)

miri64 · 2018-06-15T14:46:38Z

dist/tools/pic32prog/doc.md

+
+    https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/
+
+I downloaded a Windows 10 virtualbox image


Who is "I" (once people only see the markdown in the repo, people might wonder)?

miri64 · 2018-06-15T14:47:15Z

dist/tools/pic32prog/doc.md

+* Run PICkit3
+* Tools/Download PICkit Operating System
+  * Select `c://Program Files/Microchip/PICkit3/PK3OSV020005.hex`
+* Device should be flashed there will be a message saying the board is found


Please rephrase, this sentence is lacking grammatical structure.

miri64 · 2018-06-15T14:47:48Z

dist/tools/pic32prog/doc.md

+
+https://github.com/sergev/pic32prog
+
+Run it without the board connected


(but the PICkit3 attached)

miri64 · 2018-06-15T14:48:33Z

dist/tools/pic32prog/doc.md

+                       USBID pin: controlled by port
+```
+
+pic32prog firmware.hex


Maybe write somewhere here, that this is the actual flashing step.

cladmi · 2018-06-15T15:13:01Z

I tried to address all remarks and looked at the rendered text too: https://github.com/cladmi/RIOT/blob/pr/pic32/doc/dist/tools/pic32prog/doc.md

miri64

Minor grammar nit left. Please fix and squash immediately.

miri64 · 2018-06-15T18:01:26Z

dist/tools/pic32prog/doc.md

+
+* PICkit3-Programmer http://ww1.microchip.com/downloads/en/DeviceDoc/PICkit3%20Programmer%20Application%20v3.10.zip
+
+The steps were adapted from the archive README:


"the archive's"

To use pic32prog, the PICkit3 must be updated with a scripting mode firmware. This describes how to do it on Linux using a windows VM (free).

cladmi · 2018-06-18T08:24:00Z

Done

kYc0o · 2018-06-26T19:24:46Z

Is this ready to merge?

miri64 · 2018-06-26T19:26:19Z

Yes, just let Murdock have another go at this.

kYc0o · 2018-06-26T20:33:52Z

Murdock agrees. Go!

cladmi added Platform: MIPS Platform: This PR/issue effects MIPS-based platforms Community: help wanted The contributors require help from other members of the community labels May 31, 2018

cladmi requested review from jia200x, kYc0o and neiljay May 31, 2018 15:32

cladmi added the Area: doc Area: Documentation label May 31, 2018

cladmi mentioned this pull request May 31, 2018

pic32-wifire: add support for flashing with pic32prog #9259

Merged

miri64 reviewed Jun 5, 2018

View reviewed changes

miri64 requested changes Jun 11, 2018

View reviewed changes

cladmi mentioned this pull request Jun 12, 2018

Documentation on updating a PICkit3 sergev/pic32prog#49

Closed

miri64 requested changes Jun 13, 2018

View reviewed changes

cladmi added the CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR label Jun 15, 2018

miri64 requested changes Jun 15, 2018

View reviewed changes

cladmi force-pushed the pr/pic32/doc branch from e0c1d30 to 9708da8 Compare June 15, 2018 15:12

miri64 approved these changes Jun 15, 2018

View reviewed changes

pic32prog: add a documentation on how to update PICkit3

41105bb

To use pic32prog, the PICkit3 must be updated with a scripting mode firmware. This describes how to do it on Linux using a windows VM (free).

cladmi force-pushed the pr/pic32/doc branch from 9708da8 to 41105bb Compare June 18, 2018 08:21

cladmi added CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR and removed CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR labels Jun 18, 2018

miri64 added CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR and removed CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR labels Jun 26, 2018

kYc0o merged commit 9c612d4 into RIOT-OS:master Jun 26, 2018

cladmi deleted the pr/pic32/doc branch June 27, 2018 08:40

cladmi added this to the Release 2018.07 milestone Jul 10, 2018


		### Setup Windows VM

		You can download a free 90 days valid windows virtualbox image from:


		* PICkit3-Programmer http://ww1.microchip.com/downloads/en/DeviceDoc/PICkit3%20Programmer%20Application%20v3.10.zip

		Adapted from the README (on Windows 10 machine .NET 4.00 is already installed)


		https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/

		I downloaded a Windows 10 virtualbox image


		https://github.com/sergev/pic32prog

		Run it without the board connected


		* PICkit3-Programmer http://ww1.microchip.com/downloads/en/DeviceDoc/PICkit3%20Programmer%20Application%20v3.10.zip

		The steps were adapted from the archive README:

Conversation

cladmi commented May 31, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Contribution description

Future work

Issues/PRs references

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!

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!

miri64 left a comment

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!

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!

cladmi commented Jun 12, 2018

Uh oh!

miri64 left a comment

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!

miri64 commented Jun 15, 2018

Uh oh!

miri64 left a comment

Choose a reason for hiding this comment

Uh oh!

cladmi commented May 31, 2018 •

edited

Loading