Merge branch 'master' into publish

config.toml

@@ -520,20 +520,6 @@ theme = "doc-theme"
     parent = "tutorials@lora"
     weight = 70
 
-[[menu.main]]
-    name = "LoRa Mesh"
-    url = "/tutorials/lora/lora-mesh/"
-    identifier = "tutorials@lora@lora-mesh"
-    parent = "tutorials@lora"
-    weight = 80
-
-[[menu.main]]
-    name = "PyMesh Border Router"
-    url = "/tutorials/lora/pymesh-br/"
-    identifier = "tutorials@lora@pymesh-br"
-    parent = "tutorials@lora"
-    weight = 90
-
 [[menu.main]]
     name = "Sigfox Examples"
     url = "/tutorials/sigfox/"
@@ -1229,6 +1215,48 @@ theme = "doc-theme"
     parent = "pybytes@integrations"
     weight = 10
 
+# *** Pymesh
+[[menu.main]]
+    name = "Pymesh"
+    url = "/pymesh/"
+    identifier = "pymesh"
+    weight = 95
+
+[[menu.main]]
+    name = "Pymesh Library API"
+    url = "/pymesh/library"
+    identifier = "pymesh@library"
+    parent = "pymesh"
+    weight = 10
+
+[[menu.main]]
+    name = "Micropython API"
+    url = "/firmwareapi/pycom/network/lora/pymesh"
+    identifier = "pymesh@api"
+    parent = "pymesh"
+    weight = 20
+
+[[menu.main]]
+    name = "Simple Example"
+    url = "/pymesh/lora-mesh"
+    identifier = "pymesh@lora-mesh"
+    parent = "pymesh"
+    weight = 30
+
+[[menu.main]]
+    name = "Border Router Examplee"
+    url = "/pymesh/pymesh-br"
+    identifier = "pymesh@pymesh-br"
+    parent = "pymesh"
+    weight = 40
+
+[[menu.main]]
+    name = "Advanced Security Example"
+    url = "/pymesh/security"
+    identifier = "pymesh@security"
+    parent = "pymesh"
+    weight = 50
+
 # *** Documentation Notes
 [[menu.main]]
     name = "Documentation Notes"

content/firmwareapi/micropython/ucrypto.md

@@ -22,9 +22,7 @@ According to the **ESP32 Technical Reference Manual**, such bits "... can be use
 
 The parameter `bits` is rounded upwards to the nearest multiple of 32 bits.
 
-{{% hint style="danger" %}}
-Cryptography is not a trivial business. Doing things the wrong way could quickly result in decreased or no security. Please document yourself in the subject if you are depending on encryption to secure important information.
-{{% /hint %}}
+{{% hint style="danger" %}}Cryptography is not a trivial business. Doing things the wrong way could quickly result in decreased or no security. Please document yourself in the subject if you are depending on encryption to secure important information. {{% /hint %}}
 
 #### crypto.generate\_rsa\_signature(message, private_key, \*, pers="esp32-tls")
 
@@ -46,3 +44,61 @@ pk = f.read()
 # Generate the signature
 signature = crypto.generate_rsa_signature(header_payload, pk, pers="my_pers_string")
 ```
+
+#### crypto.rsa_encrypt\(message, public_key)
+
+Encrypts the `message` with the `public_key` of the recipient, so it will be decrypted only by the real destination.
+
+The `message` is Bytes object.
+
+The `public_key` is RSA 2048bits, it is the content of the key file (not the path to it) and it needs to be in PKCS8 format. An `openssl` example of how this key was generated is bellow.
+
+Returns the Bytes object containing the encrypted message.
+
+The usage example is at the method `crypto.rsa_decrypt()`.
+
+#### crypto.rsa_decrypt\(message, private_key)
+
+Decrypts the `message` with the `private_key`.
+
+The `message` is Bytes object.
+
+The `private_key` is RSA 2048bits, it is the content of the key file (not the path to it) and it needs to be in PKCS8 format. An `openssl` example of how this key was generated is bellow.
+
+Returns the Bytes object containing the decrypted message.
+
+```python
+# generating the public-private keys pair in a single PEM file
+$ openssl genrsa -des3 -out private.pem 2048
+# export the RSA public key to a file
+$ openssl rsa -in private.pem -outform PEM -pubout -out public.pem
+# export the RSA private key to a file
+$ openssl rsa -in private.pem -out private_unencrypted.pem -outform PEM
+
+# Example of message
+message = "this is a secret message, it needs to be encrypted"
+
+# read the key from file
+f = open("cert/public.pem")
+pk = f.read()
+f.close()
+
+# Encrypt the message
+message_encrypted = crypto.rsa_encrypt(payload, pk)
+
+# adding a SHA checksum (`uhashlib.sha()`) is encouraged,
+# so when message is decrypted consistency can be checked
+
+# ... next send the message_encrypted on the network (LoRa, Wifi, BLE, Cellular)
+
+# on the receiver try to decrypt
+
+# read the key from file
+f = open("cert/private_unencrypted.pem")
+pub = f.read()
+f.close()
+
+message_decrypted = crypto.rsa_decrypt(message_encrypted, pub)
+# additionally, the consistency should be checked (usage of `uhashlib.sha()``)
+# as the message could have been altered (attacker, network issues)
+```

content/firmwareapi/pycom/network/lora/pymesh.md

@@ -37,15 +37,26 @@ For various other complete Pymesh examples, check Tutorials & Examples section (
 
 ## Constructors
 
-#### class network.LoRa.Mesh()
+#### class network.LoRa.Mesh(*, key=masterkey)
 
 Create and configure the Mesh object.
 
-```python
+By default, the key is `0134C0DE1AB51234C0DE1AB5CA1A110F`.
 
+The current Master key can be found using: `print("Masterkey:", pymesh.cli("masterkey"))`.
+
+```python
+import ubinascii
 from network import LoRa
+
 lora = LoRa(mode=LoRa.LORAWAN, region=LoRa.EU868)
+masterkey = ubinascii.unhexlify("112233")
+mesh = lora.Mesh(key=masterkey)
 pymesh = lora.Mesh()
+
+# as test, the Masterkey can be printed
+>>> print("Masterkey:", mesh.cli("masterkey"))
+Masterkey: 11223300000000000000000000000000
 ```
 
 ## Methods

content/pymesh/_index.md

@@ -0,0 +1,32 @@
+---
+title: "Pymesh"
+aliases:
+  - pymesh/introduction
+---
+
+<img src="/gitbook/assets/pymesh/pymesh_roles.png" alt="Pymesh" width="500"/>
+
+## What is Pymesh?
+
+Pymesh is the LoRa full Mesh network technology.
+
+Mesh networks essentially get rid of gateways, which decentralises the network’s infrastructure. This then means that the network becomes flexible, so it can do many wonderful things – such as generate, change and fix itself. The success of the Mesh network is down to its parts, as any node within the network will automatically connect to the best radio-link available.
+
+Pymesh solution works on all of our LoRa supporting development boards, the LoPy4 and FiPy as well as on our OEM modules, L01 and L04.
+
+## What Pymesh offers you?
+
+* Ad-hoc communication network over raw-LoRa radio
+* Multi-gateway (Border Routers) Nodes that connect Mesh-internal data with the Cloud
+* Each Node uses LBS - Listen Before Talk
+* Security on multiple levels
+** base level: authentication and encryption using AES 128bit key, so all traffic inside Pymesh is secured
+** advanced level: RSA or AES at application level allows private communication channels above Pymesh.
+* Any LoRa device (Lopy4/Fipy) can have any of the Pymesh Node Role: Leader, Router, Child or Border Router.
+
+## Let's get started!
+
+* [Pymesh Micropython API](/firmwareapi/pycom/network/lora/pymesh)
+* [Simple Example](/pymesh/lora-mesh)
+* [Border Router Example](/pymesh/pymesh-br)
+* ​[Advanced Security Example](/pymesh/security)​

content/pymesh/library.md

@@ -0,0 +1,72 @@
+---
+title: "Pymesh Library"
+aliases:
+  - pymesh/library
+---
+
+## What is Pymesh micropython library?
+
+Pymesh micropython library is a set of scripts included (as frozen) in the Pymesh firmware binary release (Not yet released).
+
+[Open-source on github](https://github.com/pycom/pycom-libraries/tree/master/lib/pymesh)
+
+It allows users to use Pymesh in a few lines of code, as shown in the following code snippet.
+
+```python
+
+import pycom
+import time
+
+from _pymesh_config import PymeshConfig
+from _pymesh import Pymesh
+
+# stop LED heartbeat, because it will be used to indicate current Node role 
+pycom.heartbeat(False)
+
+# read config file, or set default values
+pymesh_config = PymeshConfig.read_config()
+
+#initialize Pymesh
+pymesh = Pymesh(pymesh_config, new_message_cb)
+
+while not pymesh.is_connected():
+    print(pymesh.status_str())
+    time.sleep(3)
+
+# send message to the Node having MAC address 6
+pymesh.send_mess(6, "Hello World")
+
+def new_message_cb(rcv_ip, rcv_port, rcv_data):
+    ''' callback triggered when a new packet arrived '''
+    print('Incoming %d bytes from %s (port %d):' %
+            (len(rcv_data), rcv_ip, rcv_port))
+    print(rcv_data)
+
+    # user code to be inserted, to send packet to the designated Mesh-external interface
+    # ...
+    return
+
+######################################################################################
+# Adding current node as Border Router, with a normal priority and a message handler callback
+pymesh.br_set(PymeshConfig.BR_PRIORITY_NORM, new_br_message_cb)
+
+# remove Border Router function from current node
+#pymesh.br_remove()
+
+# send data for Mesh-external, basically to the BR
+ip = "1:2:3::4"
+port = 5555
+pymesh.send_mess_external(ip, port, "Hello World")
+
+def new_br_message_cb(rcv_ip, rcv_port, rcv_data, dest_ip, dest_port):
+    ''' callback triggered when a new packet arrived for the current Border Router,
+    having destination an IP which is external from Mesh '''
+    print('Incoming %d bytes from %s (port %d), to external IPv6 %s (port %d)' %
+            (len(rcv_data), rcv_ip, rcv_port, dest_ip, dest_port))
+    print(rcv_data)
+
+    # user code to be inserted, to send packet to the designated Mesh-external interface
+    # ...
+    return
+
+```

content/pymesh/lora-mesh.md

@@ -1,12 +1,12 @@
 ---
-title: "Pymesh"
+title: "Pymesh Example"
 aliases:
     - tutorials/lora/lora-mesh.html
     - tutorials/lora/lora-mesh.md
     - chapter/tutorials/lora/lora-mesh
 ---
 
-{{% hint style="info" %}}	
+{{% hint style="info" %}}
 These API's are currently only available in the latest RC builds.
 {{% /hint %}}
 

content/pymesh/security.md

@@ -0,0 +1,39 @@
+---
+title: "Pymesh Security"
+aliases:
+  - pymesh/security
+---
+
+Pymesh supports several levels of encryption.
+
+## Mesh Masterkey
+
+Each node (Lopy/Fipy) initializes Pymesh with a 128 bits Masterkey. This is used in:
+
+* authentication
+ * a Node which does not have the Masterkey of the peer, can't connect to peer's Pymesh;
+ * further, it will create its own Pymesh, using its Masterkey, so it will become the Leader of a new Mesh network.
+* encryption
+ * all traffic inside Pymesh is encrypted with Masterkey
+  * encryption is AES-128bits.
+
+## End to end encryption
+End to end encryption is used when Node A wants to communicate securely/secretly with Node B. The data packets will be routed by other nodes, but the actual message can't be decrypted by any middle Node.
+
+This encryption can be used even for communicating between Nodes that are not in the same mesh, as message is encrypted until destination. For example, in the next picture, Node A can communicate encrypted with Node C.
+
+The challenge is in distributing the keys used for encryption(decryption), this is
+
+<img src="/gitbook/assets/pymesh/security.png" alt="Pymesh Security" width="400"/>
+
+### Symmetric encryption
+
+Symmetric-key algorithms are algorithms for cryptography that use the same cryptographic keys for both encryption of plaintext and decryption of ciphertext. More info could be checked on [Symmetric-key algorithm](https://en.wikipedia.org/wiki/Symmetric-key_algorithm).
+
+A micropython example script can be seen [here](../../firmwareapi/pycom/aes.md) using AES 128, 192 or 256 bits keys (`crypto.AES` class).
+
+### Asymmetric encryption
+
+Public-key cryptography, or asymmetric cryptography, is a cryptographic system that uses pairs of keys: public keys which may be disseminated widely, and private keys which are known only to the owner. More info could be checked on [Public-key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography).
+
+A micropython example script can be seen [here](../../firmwareapi/micropython/ucrypto.md) using RSA 2048 bits keys (`crypto.rsa_encrypt()` method).