openaps · PieterGit · Jan 2, 2018 · Jan 2, 2018
diff --git a/docs/docs/Gear Up/edison.md b/docs/docs/Gear Up/edison.md
@@ -24,7 +24,7 @@ You may need to hunt for an Edison as supplies of them are dwindling - if you ge
 
 **Note:** If you are doing Option B (an Edison from wherever you can find it) - you are getting an UNFLASHED Edison. Not a big deal - flashing it with jubilinux is just a few more steps (~15 minutes) - but remember you'll need to start with the flashing instructions. Follow the steps for flashing on (a) [all-computers page](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/all-computers-flash.html) (with the most comprehensive [troubleshooting section](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/all-computers-flash.html#troubleshooting)); b) the [Mac-specific flashing page](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/mac-flash.html); or c) the [Windows-specific flashing page](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/PC-flash.html)), but stop before installing wifi and other steps and instead jump over to the "[Install OpenAPS](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html)" page from there. 
 
-## Lithium-ion polymer (LiPo) battery or other battery supply
+## Lithium-ion polymer (LiPo) batteries
 
 Use a LiPo battery because the Explorer boards have battery charger circuitry on board for these batteries. The example setup uses a [2000mah LiPo battery](http://www.robotshop.com/en/37v-2000mah-5c-lipo-battery.html). This battery lasts approximately 16+ hours, though you could get more or less time. This battery uses a 2mm 2 pin JST connector to match the Explorer boards' power plugs. It's best to buy from a reputable supplier, because if the internal two cells are mismatched the Explorer board cannot charge them seperately and they are prone to catching fire. Make sure that it *includes a protection circuit* to protect over-discharge. **NEVER** connect the battery to an Explorer board the wrong way round. There is no manufacturing standard so never assume correct polarity. The connector JP1 on the Explorer Block has two terminals. The left side is positive, the right side is negative. The side with the JP1 label is the positive side. Typically a battery's red wire is the positive wire.  Ideally you want a battery that has a 10k ohm thermistor for temperature protection by the Edison too.
 
@@ -38,24 +38,6 @@ For people in the UK, you may find you have to shop around to find the correct b
 
 For people in Australia you can find 2000mAh, 2200mAh and 2500mAh batteries from [Little bird electronics](https://www.littlebirdelectronics.com.au/batteries/), prices are very competitive and shipping is quick. These are the same Adafruit batteries that can be obtained from the US above.
 
-### Explorer Block antenna tuning (optional)
-
-The antenna on the Explorer Block is a strip of copper underneath the green outer coating. The antenna is labeled A1. It will have its maximum power at 868 MHz. The antenna has a line across it at one point with a label that says "915". The antenna defaults to the 868 MHz range, which is what WW pumps use. If you have a US pump, mmtune will run and tune to something near 916MHz. Even with the 868 MHz antenna, you should get half a dozen feet or more of range on average.  If you (optionally) want to boost the range of your antenna by a couple more feet, then you cut through the outer coating and the copper on that line with an X-ACTO knife. A single clean cut is sufficient, but if the cut doesn't look clean you could make two cuts and then dig out the circumscribed piece and then reseal the copper with nail polish. With that cut, the antenna will have maximum power near 915 MHz.
-
-If you're unsure whether you need to cut your Explorer Block's antenna, you probably don't.  And if you decide you need slightly more range after using the Edison+Explorer rig for a few weeks, you can always come back later and do so then.
-
-![Image of Antenna](../Images/antenna0.jpg)
-
-Optional: You can also add an external antenna to the Explorer boards such [as this](http://www.mouser.com/Search/ProductDetail.aspx?R=66089-0930virtualkey65480000virtualkey620-66089-0930) from mouser.com. (Note: specific range improvement length has not been confirmed.)
-
-![Image of Antenna](../Images/antenna1.jpg)
-
-## Radio stick (only if not using Explorer board)
-
-We recommend an Explorer board with a built-in radio (see above), because if you get an Explorer board, you don't need an additional radio stick or CC-Debugger. 
-
-If you don't use an Explorer board, you can use a number of radio sticks: a [TI-USB-Sticks](http://www.ti.com/tool/cc1111emk868-915), running [subg_rfspy](https://github.com/ps2/subg_rfspy); [Wireless Things ERF](https://www.wirelessthings.net/erf-0-1-pin-spaced-radio-module); [Wireless Things Slice of Radio](https://www.wirelessthings.net/slice-of-radio-wireless-rf-transciever-for-the-raspberry-pi) a Slice of Radio; or a Rileylink. For details about setup with these other stick and board options, [the best instructions will be found in the mmeowlink wiki](https://github.com/oskarpearson/mmeowlink/wiki) for setting up your board and stick. Note you may also need a CC debugger for these. Then, come back to Phase 1 of the docs once you complete that.
-
 ## USB Cables
 
 You will need two micro USB cables - with a micro connector on one end and a standard (Type A) connector on the other. Most cables will work fine, but some prefer to select lengths. You may already have one for charging a Dexcom receiver, or an Android phone, lying around at home. If you don't, here's an example of one that will work: [Monoprice Premium USB to Micro USB Charge, Sync Cable - 3ft](http://www.monoprice.com/Product?c_id=103&cp_id=10303&cs_id=1030307&p_id=9763&seq=1&format=2).
@@ -64,7 +46,27 @@ Warning: bad cables cause a lot of headaches during the Edison flashing process,
 
 ## Micro USB to Micro USB OTG Cable
 
-You may need to connect your Dexcom Receiver to your Explorer Block for offline looping.  For this you will need to use a micro USB to micro USB OTG cable (or an OTG adapter). Here is an example of a cable that will work: [BestGameSetups Micro USB to Micro USB OTG (On-The-Go) 12" (30cm) Data Cable](https://www.amazon.com/dp/B00TQOEST0/ref=cm_sw_r_cp_api_Niqfzb3B4RJJW).
+You may need to connect your Dexcom Receiver to your Explorer Block for offline looping. For this you will need to use a micro USB to micro USB OTG cable (or an OTG adapter). Here is an example of a cable that will work: [BestGameSetups Micro USB to Micro USB OTG (On-The-Go) 12" (30cm) Data Cable](https://www.amazon.com/dp/B00TQOEST0/ref=cm_sw_r_cp_api_Niqfzb3B4RJJW). On E-bay they can be found as [30 cm Right Angle Micro USB B to Host OTG Cable](https://www.ebay.com/sch/30%20cm%20Right%20Angle%20Micro%20USB%20B%20to%20Host%20OTG%20Cable). At least 10" (25cm) is recommended.
+
+Note that:
+- if you connect your Dexcom Receiver by USB, you will also need to use use a 5V USB battery power supply to your UART port.
+- the Explorer board micro USB ports are quite fragile, so make sure they won't cause tention on the explorer board. If your micro usb port is broken, see [Troubleshooting Edison Hardware page](http://openaps.readthedocs.io/en/latest/docs/Troubleshooting/Edison-hardware-troubleshooting.html).
+
+## USB Battery Power Supply
+
+A large-capacity power supply that is greater than 6500 mAh (milliAmp-hours) is
+recommended for 16h+ use with a Dexcom Receiver attached to your Explorer board.
+Make sure that the battery has at least one 2.1 Amp USB output. 
+A battery with a form-factor that minimizes size is recommended,
+to allow the patient to be as ambulatory as possible. When you have a full
+OpenAPS implemented and working, you will want to have multiple batteries to
+rotate and recharge. A battery that can deliver power while it charges (often called pass through charging) is ideal
+as you will be able to charge it on-the-fly without shutting down and restarting your rig.
+
+Examples are:
+- [Zendure A2 Portable Charger, 6700 mAh, 2.1A Max (Zendure.com)](https://zendure.com/collections/a-series-portable-chargers)
+- [Zendure A3 Portable Charger 10000mAh, 2.1A Max (Amazon.com)](http://www.amazon.com/Zendure-2nd-Portable-Charger-10000mAh/dp/B014RBEAQC/ref=sr_1_1)
+- [TeckNet portal chargers >= 10000 mAh, > 2.1A Max (Amazon.co.uk)](https://www.amazon.co.uk/s/s/ref=sr_nr_p_89_0?srs=1644314031&fst=as%3Aoff&rh=n%3A560798%2Cn%3A%21560800%2Cn%3A1340509031%2Cn%3A560826%2Cn%3A340327031%2Cn%3A5520530031%2Cp_89%3ATeckNet&bbn=5520530031&ie=UTF8&qid=1514929760&rnid=1632651031)
 
 ## Nuts and Bolts
 
@@ -92,6 +94,26 @@ There are a few 3D-printed cases that are being designed, so check back here for
 * [TallyGear soft case](http://www.tallygear.com/index.php?route=product/category&path=120) - these are the soft cases Dana uses ([see this example](https://twitter.com/danamlewis/status/792782116140388353)). The OpenAPS-sized case can be made any any pattern/fabric she uses elsewhere on the site.
 * [JD Burrows SD card case](https://www.officeworks.com.au/shop/officeworks/p/j-burrows-sd-and-usb-case-blue-jbsdcasbu) - this is a hard / soft case which fits the rig with a 2500mAh battery perfectly, can also fit a spare AAA pump battery (Australia)
 
-## Other Options
+### Heat shrinking tubing
+
+Instead of using a hard or soft case you can also use [Heat Shrink Tubing](https://www.amazon.com/gp/product/B009IILEVY).
+
+### Advanced hardware options
+
+## Explorer Block antenna tuning (optional)
+
+The antenna on the Explorer Block is a strip of copper underneath the green outer coating. The antenna is labeled A1. It will have its maximum power at 868 MHz. The antenna has a line across it at one point with a label that says "915". The antenna defaults to the 868 MHz range, which is what WW pumps use. If you have a US pump, mmtune will run and tune to something near 916MHz. Even with the 868 MHz antenna, you should get half a dozen feet or more of range on average.  If you (optionally) want to boost the range of your antenna by a couple more feet, then you cut through the outer coating and the copper on that line with an X-ACTO knife. A single clean cut is sufficient, but if the cut doesn't look clean you could make two cuts and then dig out the circumscribed piece and then reseal the copper with nail polish. With that cut, the antenna will have maximum power near 915 MHz.
+
+If you're unsure whether you need to cut your Explorer Block's antenna, you probably don't.  And if you decide you need slightly more range after using the Edison+Explorer rig for a few weeks, you can always come back later and do so then.
+
+![Image of Antenna](../Images/antenna0.jpg)
 
-* [Heat Shrink Tubing](https://www.amazon.com/gp/product/B009IILEVY)  
+Optional: You can also add an external antenna to the Explorer boards such [as this](http://www.mouser.com/Search/ProductDetail.aspx?R=66089-0930virtualkey65480000virtualkey620-66089-0930) from mouser.com. (Note: specific range improvement length has not been confirmed.)
+
+![Image of Antenna](../Images/antenna1.jpg)
+
+## Radio stick (only if not using Explorer board)
+
+We recommend an Explorer board with a built-in radio (see above), because if you get an Explorer board, you don't need an additional radio stick or CC-Debugger. 
+
+If you don't use an Explorer board, you can use a number of radio sticks: a [TI-USB-Sticks](http://www.ti.com/tool/cc1111emk868-915), running [subg_rfspy](https://github.com/ps2/subg_rfspy); [Wireless Things ERF](https://www.wirelessthings.net/erf-0-1-pin-spaced-radio-module); [Wireless Things Slice of Radio](https://www.wirelessthings.net/slice-of-radio-wireless-rf-transciever-for-the-raspberry-pi) a Slice of Radio; or a Rileylink. For details about setup with these other stick and board options, [the best instructions will be found in the mmeowlink wiki](https://github.com/oskarpearson/mmeowlink/wiki) for setting up your board and stick. Note you may also need a CC debugger for these. Then, come back to Phase 1 of the docs once you complete that.
diff --git a/docs/docs/Images/edisonmicrousb_broken.png b/docs/docs/Images/edisonmicrousb_broken.png
diff --git a/docs/docs/Images/edisonmicrousb_chemwik.png b/docs/docs/Images/edisonmicrousb_chemwik.png
diff --git a/docs/docs/Images/edisonmicrousb_edisonglued.png b/docs/docs/Images/edisonmicrousb_edisonglued.png
diff --git a/docs/docs/Images/edisonmicrousb_edisonview.png b/docs/docs/Images/edisonmicrousb_edisonview.png
diff --git a/docs/docs/Images/edisonmicrousb_edisonviewreal.png b/docs/docs/Images/edisonmicrousb_edisonviewreal.png
diff --git a/docs/docs/Images/edisonmicrousb_microusb_cablecolors.png b/docs/docs/Images/edisonmicrousb_microusb_cablecolors.png
diff --git a/docs/docs/Images/edisonmicrousb_microusb_pinout.png b/docs/docs/Images/edisonmicrousb_microusb_pinout.png
diff --git a/docs/docs/Images/edisonmicrousb_mintbox.png b/docs/docs/Images/edisonmicrousb_mintbox.png
diff --git a/docs/docs/Troubleshooting/Edison-hardware-troubleshooting.md b/docs/docs/Troubleshooting/Edison-hardware-troubleshooting.md
@@ -0,0 +1,54 @@
+# Troubleshooting hardware problems with Edison rig
+
+## Fix Edison Block micro usb ports
+
+The Edison Block micro usb ports are quite fragile. If it breaks it can be restored by soldering a short USB cable to the Explorer Block. 
+This is only needed if you use a Dexcom receiver and you need to power the rig with a USB battery. If you use a LiPo battery both micro usb connectors can charge the LiPo battery.
+
+This isn't an easy soldering job. This is of course at own risk and it might make break your rig completely if you screw up.
+
+Example steps if your USB UART port is broken. That will look like this:
+
+![Broken USB UART port](../Images/edisonmicrousb_broken.png)
+
+Steps:
+1. Remove your Edison from the Edison block.
+2. Use a good soldering iron, helping hands (with magnifying glass and lamp), good lighting and a glue gun.
+3. Use desoldering braid to remove excess of solder from the micro usb connectors. E.g. with [Chemtronics Chem-Wik Rosin](https://www.chemtronics.com/chem-wik-rosin).
+
+![Chemtronics Chem-Wik Rosin](../Images/edisonmicrousb_chemwik.png)
+
+4. Check the micro usb pin out and cable colors. For powering you need a red wire connected to Vcc (5V) and a black wire connected to GND. You don't need to connect the green wire (Data-) and white wire (Data+), but you will loose the UART capability.
+   If you need the serial line of the USB UART you will need to connect them, but it's much easier to use your Edison in another Edison breakout board or Edison block if you need to have a USB serial connection.
+   Don't cut the green and wire too short (like I did), because can you can use them to make the glue connection from the cable to the board a bit more sturdy.
+   Pin 4 of the USB OTG (USB On The Go) (blue in the picture) is used for `USB_ID`. It's unused for the USB UART connection.
+   If you need the full PCB, schematics and electronic design, check [EnhancedRadioDevices GitHub](https://github.com/EnhancedRadioDevices/915MHzEdisonExplorer)
+
+![edisonmicrousb_microusb_pinout.png (thanks thice.nl)](../Images/edisonmicrousb_microusb_pinout.png)
+
+![edisonmicrousb_microusb_cablecolors.png (thanks tomsguide.com)](../Images/edisonmicrousb_microusb_cablecolors.png)
+
+![edisonmicrousb_edisonview.png](../Images/edisonmicrousb_edisonview.png)
+
+5. If you succeed it should look a bit like this:
+
+![edisonmicrousb_edisonviewreal.png](../Images/edisonmicrousb_edisonviewreal.png)
+
+6. Use a digital multimeter to check that the wires don't short.
+
+7. Screw back the Edison on the Edison block and test the connection (log into Edison with SSH, check to see if `lsusb` recognizes the Dexcom Receiver and see if it's still looping)
+
+8. Remove the Edison before glueing 
+
+9. Use a tie wrap in the Edison Block hole to make sure the cable won't move and bend it a bit towards the side to which the cable is connected to the Edison Block.
+
+10. Use a glue gun to make sure the wires are stuck to the Explorer block and don't move.
+
+![edisonmicrousb_edisonglued.png](../Images/edisonmicrousb_edisonglued.png)
+
+11. Put it in a case. I don't have a new 3D case yet, so I use a TickTac freshmints box (with some extra holes for cooling) for now. The result:
+
+![edisonmicrousb_mintbox.png](../Images/edisonmicrousb_mintbox.png)
+
+12. Use [this GitHub issue](https://github.com/EnhancedRadioDevices/915MHzEdisonExplorer/issues/22) to report your findings. I hope you succeeded.
+    You can ask [Enhanced Radio Devices Support](https://enhanced-radio-devices.myshopify.com/pages/shipping-and-faqs) or tag PieterGit on the Gitter Intend to Bolus channel for help.
diff --git a/docs/docs/Troubleshooting/index.rst b/docs/docs/Troubleshooting/index.rst
@@ -9,3 +9,4 @@ Troubleshooting
    Pump-rig-communications-troubleshooting
    CGM-rig-communications-troubleshooting
    Rig-NS-communications-troubleshooting
+   Edison-hardware-troubleshooting.md