Rock64 usb2.0 Power Control Floating GPIO Tutorial Files & Notes

[MarkHaysHarris777]

Greetings,

   The purpose of this post is to document the rock64_usb_power_service.sh script , provide instructions and notes for its correct use (tutorial) , and document the installation of the script as a systemd automated service.  

   The problem that we are solving is that the usb2.0 power regulators are controlled by a hardware line (EN) (gpio2) which is in a floating state when the Rock64 boots.   This often results in the usb2.0 ports losing power ( at least momentarily ).  

   The solution to this problem is to create an executable script , as well an automated service (systemd) , that will export the gpio2 line to user space ( setting it low & turning ON the power regulators ) while also allowing the system admin (user) to control the gpio2 for power cycling devices plugged into the usb2.0 port.  This approach to fixing this problem is a win-win in that the usb2.0 power remains on permanently after  boot-up for those who want it, and it also allows advanced users the flexibility of being able to power cycle their usb2.0 ports as designed by the Rock64 engineers ( very handy in many use cases ).

   The user has complete freedom and control because the script may be run manually (as root) or it may be installed as an automated systemd service.  The following tutorial will provide the codes first , then I will discuss how to use them , and finally how to install the usb_gpio_on.service  in systemd.  After each code section I will give instructions for 1) where to place the script, 2) what permissions to give it, 3) what ownership to give it, and finally how to run it.

The Scripts


   Before beginning switch into root operating mode ( and permissions ) with  sudo -i  (important).

rock64_usb_power_service.sh

Code:

#!/bin/bash
# rock64_usb_power_service.sh
#
# Mark H. Harris
# v0.1b
#
#
PWRON=0
PWROFF=1
GP=2
GPOUT="out"
GPPATH="/sys/class/gpio"
GPVALUE="value"
GPMODE="direction"

## remove gpio if already exported
if [ -d $GPPATH/gpio$GP ]
then
   echo $GP > $GPPATH/unexport
   sleep 2
fi

# export the gpio, and set if ready
echo $GP > $GPPATH/export
sleep 2
if [ -e $GPPATH/gpio$GP/$GPMODE ]
then
   echo $GPOUT > $GPPATH/gpio$GP/$GPMODE
   sleep 2
   echo $PWRON > $GPPATH/gpio$GP/$GPVALUE
fi

   The  rock64_usb_power_service.sh  is the executable script.  Place this script in  /usr/local/sbin/

   Check the spelling very carefully;  or things will not work when it comes time to automate the service.

   set the ownership, group, and permissions:
   
   cd  /usr/local/sbin/
   chown  root  rock64_usb_power_service.sh
   chgrp  root  rock64_usb_power_service.sh
   chmod  0754  rock64_usb_power_service.sh

   To run the script manually :

   sudo  -i
   /usr/local/sbin/rock64_usb_power_service.sh

   To power cycle the usb2.0 port's 5v :

   sudo -i
   echo 1  >  /sys/class/gpio/gpio2/value
   echo 0  >  /sys/class/gpio/gpio2/value

   The above script exports the (EN)  gpio2 mux line to user space using the sysfs method,  sets the direction "out", and sets the value 0 ( pulling the line low turns ON the usb2.0 power regulators ).


usb_gpio_on.service

Code:

[Unit]
Description=set the gpio2 EN line low for usb2.0 power regulator ON

[Service]
ExecStart=/usr/local/sbin/rock64_usb_power_service.sh
Type=oneshot

[Install]
WantedBy=default.target

   The above  usb_gpio_on.service  script is called a systemd  "service unit file".  This file describes the service to systemd so that systemd knows how to find the executable, and further knows that the service executable only needs to be run once.  Again, it is very critical that all the spelling is precise;  miss spellings will result is chaos;  and of course no fix.

   Place this file  usb_gpio_on.service  in directory  /etc/systemd/system/

   Set the ownership, group, and permissions for this file :

   cd  /etc/systemd/system/
   chown  root  usb_gpio_on.service
   chgrp  root  usb_gpio_on.service
   chmod  0664  usb_gpio_on.service

   Inform systemd that a change has been made to the unit files on disk       (very critical)

   systemctl  daemon-reload
   systemctl  enable  usb_gpio_on.service

   Congratulations!   At this point the service has successfully run;  the gpio2 has been exported, and the gpio2 pin has been pulled low turning on the usb2.0 power regulators.  

   We are now done;  all that is left to do is to reboot your Rock64 ! 

   You can check that this worked after reboot by looking in  /sys/class/gpio/  for an export directory  called  gpio2!   

   At this point you may go about life on your Rock64 normally -- the usb2.0 power should not drop because the EN line is no longer floating;  however,  if you like you still have the option to power cycle the usb2.0 ports using the method I detailed above.


Caveat Emptor

If you want to try this tutorial follow two simple rules , or do so at your own risk.  Either wait for me to post on the forum that this has been tested multiple times and is 1) safe,  and 2) works;   or become a beta tester ( a guinea pig ).  That means that you contact me on irc and tell me you're testing and that you will be gracious to provide feedback ( including loss of time and|or hair )  so that I know who is using it so far, and whether I need to fix anything or make anything clearer.

Every effort has been made to ensure that this is accurate and free from defects;  but we all know the best laid plans of mice and of programmers.

We may at some future point fix this in the dts|dtb file and place in a future image;  the problem with that is that users who wish to have the advanced ability to power cycle the usb ports as designed would have to hack the dts first!  So we're going to try this and see how it goes.

This method and the script which have been provided have been tested according to this tutorial on my Rock64 production test board, and everything works on my board as described in this tutorial;  again, if I need to make anything more clear, or if something is broken ( I certainly hope not ) please let me know asap , preferably on irc.

Thanks much !   

---