Added Pygate Docs (#265)

peter-pycom · web-flow · commit 21d3913f218d · 2020-05-25T18:36:14.000+03:00
Added pygate/pyeth: split into api and tutorial
diff --git a/config.toml b/config.toml
@@ -702,6 +702,13 @@ theme = "doc-theme"
     parent = "firmwareapi@pycom@machine"
     weight = 60
 
+[[menu.main]]
+    name = "Pygate"
+    url = "/firmwareapi/pycom/machine/pygate/"
+    identifier = "firmwareapi@pycom@machine@pygate"
+    parent = "firmwareapi@pycom@machine"
+    weight = 65
+
 [[menu.main]]
     name = "RMT"
     url = "/firmwareapi/pycom/machine/rmt/"
@@ -779,6 +786,13 @@ theme = "doc-theme"
     parent = "firmwareapi@pycom@network"
     weight = 20
 
+[[menu.main]]
+    name = "Ethernet"
+    url = "/firmwareapi/pycom/network/eth/"
+    identifier = "firmwareapi@pycom@network@eth"
+    parent = "firmwareapi@pycom@network"
+    weight = 25
+
 [[menu.main]]
     name = "Bluetooth"
     url = "/firmwareapi/pycom/network/bluetooth/"
diff --git a/content/firmwareapi/pycom/machine/pygate.md b/content/firmwareapi/pycom/machine/pygate.md
@@ -0,0 +1,39 @@
+---
+title: "Pygate"
+aliases:
+    - firmwareapi/pycom/machine/pygate.html
+    - firmwareapi/pycom/machine/pygate.md
+    - chapter/firmwareapi/pycom/machine/pygate
+---
+
+The Pygate is an 8-channel LoRaWAN gateway. You connect a WiPy or Gpy board to the Pygate and flash a firmware build where the Pygate functionality is enabled. See the [Pygate tutorial](/tutorials/all/pygate) to get started.
+
+## Methods
+
+#### machine.pygate\_init(buff)
+
+This function is used to initialize the Pygate
+
+- `buff`: the data contents of the gateway global config json file
+
+#### machine.pygate\_deinit()
+
+This shuts down the concentrator.
+
+#### machine.callback(trigger, handler=None, arg=None)
+
+- `trigger`: A trigger event(s) for invoking the callback function `handler`, the triggers/events are:
+
+	`machine.PYGATE_START_EVT`
+
+	`machine.PYGATE_STOP_EVT`
+
+	`machine.MP_QSTR_PYGATE_ERROR_EVT`
+
+- `handler`: The callback function to be called.  When not passed to function, any pre-registered callback will be disabled/removed.
+
+- `arg`: Optional argument to be passed to the callback function.
+
+#### machine.events()
+
+Get the Pygate events
diff --git a/content/firmwareapi/pycom/network/eth.md b/content/firmwareapi/pycom/network/eth.md
@@ -0,0 +1,65 @@
+---
+title: "Ethernet"
+aliases:
+    - firmwareapi/pycom/network/eth.html
+    - firmwareapi/pycom/network/eth.md
+    - chapter/firmwareapi/pycom/network/eth
+---
+
+The ETH class enables the use of an ethernet connection via the PyEthernet board plugged into a Pygate.
+
+---
+*NOTE* :
+Ethernet support is only available in special Gpy or WiPy firmware builds where this feature has been enabled.
+
+---
+
+## Constructors
+
+### class network.ETH(id=0, ...)
+
+Create and configure an ETH object. See init for params of configuration.
+
+```python
+from network import ETH
+eth = ETH()
+```
+
+## Methods
+
+
+### eth.init(hostname=None)
+
+This function starts the Ethernet interface and enables the ethernet adapter.
+
+`hostname`: set the interface hostname
+
+### eth.ifconfig(config=\['dhcp' or configtuple\])
+
+With no parameters given, this returns a 4-tuple of (ip, subnet mask, gateway, DNS server).
+
+Optionally specify the configuration parameter:
+
+- `config='dhcp'`  
+
+If 'dhcp' is passed as a parameter, then the DHCP client is enabled and the IP parameters are negotiated with the DHCP server.
+
+- `config=(ip, nm, gw, dns)`
+
+If the 4-tuple config is given then a static IP is configured. For example: `eth.ifconfig(config=('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))`.
+
+### eth.hostname(string)
+
+Set the interface host name.
+
+### eth.mac()
+
+Get the ethernet interface mac address.
+
+### eth.deinit()
+
+Shuts down the ethernet interface.
+
+### eth.isconnected()
+
+Returns `True` if the ethernet link is up and IP is accquired, `False` otherwise.
diff --git a/content/tutorials/all/PyGate.md b/content/tutorials/all/PyGate.md
@@ -1,18 +1,37 @@
 ## Pygate
 
-__To connect your Pygate to a LoRa server, follow these steps:__  
+The Pygate is an 8-channel LoRaWAN gateway. This page will help you get started with it.
 
-1- Attach a Pycom development board e.g. a Wipy, LoPy4, GPy, to the Pygate. (The RGB LED of the development board should be aligned with the USB port of PyGate)
+### Quickstart
 
-2- Attach the LoRa Antenna to the Pygate 
+To connect your Pygate to a LoRa server, follow these steps:
 
-3- Flash the Pycom Device with latest PyGate Firmware.
+1. Attach a Wipy, or GPy to the Pygate. The RGB LED of the development board should be aligned with the USB port of the Pygate.
+1. Attach the LoRa Antenna to the Pygate.
+1. Flash the Pycom Device with with a firmware build where Pygate functionality is enabled.
+1. Create a `config.json` for your Pygate and upload it.
+1. Create a `main.py` that creates an uplink and runs the Pygate packet fowarder.
+1. Run the `main.py`.
+1. Now it is operational. The communication from other LoRa nodes such as a LoPy4 will now reach the gateway and will receive up and downlink via the PyGate.
+1. To stop the Pygate at any time press Ctrl-C on the REPL and run `machine.pygate_deinit()`. It will take a few seconds to stop the gateway tasks and safely power-off the concentrator.
 
-4- Upload the Gateway configuration json file onto the attached Pycom device (via Pymakr on Atom or VSCode). Depending on the type of Pygate (EU868/US915) you should have different config files.
 
-__The following example will demonstrate a simple script for getting started with a Pygate via a Wifi connection for the EU868 region:__
+Make sure you supply a config matching your region (EU868, US915, etc), e.g. https://github.com/Lora-net/packet_forwarder/tree/master/lora_pkt_fwd/cfg. If you are in EU region, it should be sufficent to update the example below with your GW ID, the LoRa server address and port number.
+
+
+### Example TTN Wifi
+
+The following example shows the script and json file to run the Pygate over Wifi connecting to [The Things Network](https://www.thethingsnetwork.org/).
+
+ * log in to https://console.thethingsnetwork.org/
+ * go to Gateways and register a new gateway
+ * select "I'm using a legacy packet forwarder"
+ * enter a EUI (8 byte hexadecimal value) - also enter this in your `config.json` for `gateway_ID` (Just enter the digits without the "eui-" prefix)
+ * select your Frequency Plan
+ * select a router - also enter the hostname in your `config.json` for `server_address`
+ * enter your wifi SSID and password in `main.py`
+
 
-You can use the same file, just enter your GW unique ID, the LoRa server address and port numbers.
 
 ```python
 from network import WLAN
@@ -21,10 +40,10 @@ import machine
 from machine import RTC
 import pycom
 
-#Disable Hearbeat
+# Disable Hearbeat
 pycom.heartbeat(False)
 
-#Define callback function for Pygate Events
+# Define callback function for Pygate events
 def machine_cb (arg):
     evt = machine.events()
     if (evt & machine.PYGATE_START_EVT):
@@ -36,10 +55,9 @@ def machine_cb (arg):
     elif (evt & machine.PYGATE_STOP_EVT):
         # RGB off
         pycom.rgbled(0x000000)
-        
-# register Callback func
-machine.callback(trigger = (machine.PYGATE_START_EVT |
-machine.PYGATE_STOP_EVT | machine.PYGATE_ERROR_EVT), handler=machine_cb)
+
+# register callback function
+machine.callback(trigger = (machine.PYGATE_START_EVT | machine.PYGATE_STOP_EVT | machine.PYGATE_ERROR_EVT), handler=machine_cb)
 
 # Connect to a Wifi Network
 wlan = WLAN(mode=WLAN.STA)
@@ -50,20 +68,20 @@ while not wlan.isconnected():
 
 print("Wifi Connection established")
 
-#Sync time via NTP server for GW timestamps on Events
+# Sync time via NTP server for GW timestamps on Events
 rtc = RTC()
 rtc.ntp_sync(server="0.nl.pool.ntp.org")
 
-#Read the GW config file from Filesystem
+# Read the GW config file from Filesystem
 fp = open('/flash/config.json','r')
 buf = fp.read()
 
-# Start Pygate
+# Start the Pygate
 machine.pygate_init(buf)
 
 ```
 
-A sample Config json file for GW configuration on EU868 region:
+A sample `config.json` file for gateway configuration in EU868 region:
 
 ```json
 {
@@ -253,132 +271,3 @@ A sample Config json file for GW configuration on EU868 region:
 	}
 }
 ```
-To stop the Pygate at any time use:
-
-- REPL -> use CTRL-C
-- using deinit function `machine.pygate_deinit()`
-
-This will stop GW tasks and safely power-off the Concentrator.
-
-
-__Note__: The Pygate packet forwarder is a legacy packet forwarder, so you must make sure you use select the legacy packet forwarder option in TTN as shown below.
-
-![alt_text](https://wiki.dragino.com/images/c/c6/TTN_Create_Gateway_0.png)
-
-
-## Pygate APIs
-
-###machine Module
-
-#### machine.pygate\_init([buff])
-
-This function is used to initialize the Pygate 
-
-- `buff`: the data contents of the gateway global config json file
-
-When no parameter is passed to function the Pygate is just powered on. (will be useful when using pygate as just a concentrator controllable via uart by another device eg. RPi)
-
-#### machine.pygate\_deinit()
-
-This shuts down the concentrator.
-
-#### machine.pygate\_cmd\_decode(buff)
-
-This sends the LoRa gateway command to the concentrator. This is useful when packet forwarder / HAL software is run on a different device (e.g. Rpi) and commands to the concentrator are passed to the Pygate via UART.
-
-#### machine.pygate\_cmd\_get()
-
-This gets the command execution result from concentrator.
-
-An example script demonstrating running packet forwarder software on a different device:
-
-```python
-from machine import UART
-import machine
-import time
-import os
-import gc
-
-machine.pygate_init(None)
-time.sleep(3)
-
-uart = UART(1, 115200, timeout_chars=40, pins=('P23', 'P22'))
-
-while True:
-    if uart.any():
-        rx_data = uart.read()
-        machine.pygate_cmd_decode(rx_data)
-        tx_data =  machine.pygate_cmd_get()
-        l = uart.write(tx_data)
-    else:
-        time.sleep_us(10)
-```
-
-#### machine.callback(trigger, handler=None, arg=None)
-
-- `trigger`: A trigger event(s) for invoking the callback function `handler`, the triggers/events are:
-
-	`machine.PYGATE_START_EVT`
-
-	`machine.PYGATE_STOP_EVT`
-
-	`machine.MP_QSTR_PYGATE_ERROR_EVT`
-
-- `handler`: The callback function to be called.  When not passed to function, any pre-registered callback will be disabled/removed.
-
-- `arg`: Optional arg to be bassed to callback function.
-
-#### machine.events()
-
-Get the Pygate events
-
-
-## Pygate Ethernet adapter APIs
-
-`network.ETH` module
-
-### ETH.init(hosname=None)
-
-This function starts the Ethernet interface and enables the ethernet adapter.
-
-`hostname`: set the interface hostname
-
-### ETH.	ifconfig(config=\['dhcp' or configtuple\])
-
-With no parameters given, this returns a 4-tuple of (ip, subnet_mask, gateway, DNS_server).
-
-If DHCP is passed as a parameter, then the DHCP client is enabled and the IP params are negotiated with the DHCP server.
-
-If the 4-tuple config is given then a static IP is configured. For instance:
-
-`eth.ifconfig(config=('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))`
-
-### ETH.hostname(string)
-
-Set the interface host name.
-
-### ETH.mac()
-
-Get the ethernet interface mac address.
-
-### ETH.deinit()
-
-Shuts down the ethernet interface.
-
-### ETH.isconnected(Bool)
-
-Returns `True` if the ethernet link is up and IP is accquired, `Fasle` if otherwise
-
-### ETH.register(reg, cmd, value)
-
-Write/read specific register from/to the ksz8851 ethernet controller
-
-`cmd`: 0 to read , 1 to write
-
-Ex: to read register 0x90
-
-`eth.register(0x90,0)`
-
-To write:
-
-`eth.register(0x90, 1, 0x0000)`
