comments and doc

Author: sasilva1998

README.md

@@ -1,2 +1,51 @@
 # uPy-rosserial
-This is an implementation of rosserial for MicroPython, here everything needed will be found.
+`rosserial` a method used by ROS in order to establish communication via serial , mostly this is used with microcontrollers, which in this case are the ones responsible in some ROS applications for actuators and sensors usage.
+
+Since there is no rosserial package for uPy as there is for Arduino, this repo has been created where every needed script to establish rosserial with uPy will be found.
+
+## Features
+- [x] Advertising Topics
+- [x] Publishing
+- [ ] Subscribing
+- [ ] Actions
+- [ ] Services
+
+**To Do: Subscribing testing and implementation.**
+
+## Installation
+In theory every board with the kind of generic `UART` class for ESP32 is capable of using this library, but it must be known exactly which `UART ID` is being used, this means for example, for ESP32 defined pins correspond to TX0 and RX0 for UART0, and so on. In the examples below, UART2 is used.
+
+In order to use ros node communication, have in mind a python class for each message must be available. this means a dependency of this library is [uPy Genpy](https://github.com/FunPythonEC/uPy-genpy), used to create Python classes for messages from `*.msg` files. Follow the installation from `ugenpy` before proceeding.
+
+Once `ugenpy` is inside, the packages `uros` and `rosserial_msgs` from `src` folder from this repository must be copied to the flash memory. I strongly recommend using [rshell](https://github.com/dhylands/rshell).
+>Note: Soon this will be available to be installed with upip.
+
+**Have in mind before publishing or subscribing to a topic, the message class must be generated with `ugenpy`**
+
+## Usage
+### Publish example
+
+Suppose `ColorRGBA.py` has been created using `ugenpy` and `ColorRGBA.msg` file:
+```
+float32 r
+float32 g
+float32 b
+float32 a
+```
+
+And then running the following e.g.:
+
+``` python
+import uros
+from std_msgs._ColorRGBA import ColorRGBA #message object ColorRGBA
+from time import sleep
+node=uros.NodeHandle(2,115200) #node initialized, for tx2/rx2 and 115200 baudrate
+msg=ColorRGBA() #msg object init
+msg.r=1 #values to variables assigned
+msg.g=3
+msg.b=4
+msg.a=1
+while True:
+    node.publish('Colorsh',msg) #publish data to node Colorsh
+    sleep(1)
+```

src/rosserial_msgs/_TopicInfo.py

@@ -81,7 +81,7 @@ def deserialize(self, str):
 			self.md5sum = str[start:end].decode('utf-8')
 			start = end
 			end += 4
-			(self.buffer_size,) = _get_struct_i().unpack(str[start:end])
+			(self.buffer_size,) = struct.unpack('<i',str[start:end])
 			return self
 		except Exception as e:
 			print(e)

src/uros/core.py

@@ -1,27 +1,45 @@
+#libraries needed
+#	machine: for uart usage
+#	uio: packet buffer
+#	struct: serlization
+#	_TopicInfo: for topic negotiation
+
 import machine as m
 import uio
-import struct
+import ustruct as struct
 from time import sleep, sleep_ms, sleep_us
 from rosserial_msgs._TopicInfo import TopicInfo
 
+#rosserial protocol header
 header=[0xff,0xfe]
 
+#class to manage publish and subscribe
+#COULD BE CHANGED AFTERWARDS
 class NodeHandle(object):
 	def __init__(self, serial_id, baudrate):
 
+		"""
+		id: used for topics id (negotiation)
+		advertised_topics: manage alreade negotiated topics
+		serial_id: uart id
+		baudrate: baudrate used for serial comm
+		"""
 		self.id=1
-
 		self.advertised_topics=dict()
 		self.serial_id=serial_id
 		self.baudrate=baudrate
 		self.uart = m.UART(self.serial_id, self.baudrate)
 		self.uart.init(self.baudrate, bits=8, parity=None, stop=1, txbuf=0)
 
-	def init_node(self):
-		pass
 
+	#method to manage and advertise topic
+	#before publishing or subscribing
 	def _advertise_topic(self,topic_name, msg):
 
+		"""
+		topic_name: eg. (/std_msgs/Greet)
+		msg: message object
+		"""
 		register=TopicInfo()
 		register.topic_id=self.id
 		register.topic_name=topic_name
@@ -30,34 +48,37 @@ def _advertise_topic(self,topic_name, msg):
 
 		self.advertised_topics[topic_name]=self.id
 
+		#id are summed by one
 		self.id+=1
 
 		try:
 			register.buffer_size=msg.buffer_size
-		except:
-			pass
+		except Exception as e:
+			print(e)
 
 		#serialization
 		packet=uio.StringIO()
 		register.serialize(packet)
 
+		#already serialized (packet)
 		packet=list(packet.getvalue().encode('utf-8'))
 		length=len(packet)
 
+		#both checksums
 		crclen=[checksum(le(length))]
 		crcpack=[checksum([0,0]+packet)]
 
 		#final packet to be sent
 		fpacket=header+le(length)+crclen+[0,0]+packet+crcpack
-
 		self.uart.write(bytearray(fpacket))
 
 
-
 	def publish(self,topic_name,msg):
+
 		if topic_name not in self.advertised_topics:
 			self._advertise_topic(topic_name, msg)
 
+		#same as advertise
 		packet=uio.StringIO()
 		msg.serialize(packet)
 
@@ -74,10 +95,10 @@ def publish(self,topic_name,msg):
 	def subscribe(self):
 		pass
 
-
+#checksum method, receives array
 def checksum(arr):
     return 255-((sum(arr))%256)
-
+#little-endian method
 def le(h):
     h &= 0xffff
     return [h & 0xff, h >> 8]

tests/colorrgba.py

@@ -0,0 +1,12 @@
+import uros
+from std_msgs._ColorRGBA import ColorRGBA #message object ColorRGBA
+from time import sleep
+node=uros.NodeHandle(2,115200) #node initialized, for tx2/rx2 and 115200 baudrate
+msg=ColorRGBA() #msg object init
+msg.r=1 #values to variables assigned
+msg.g=3
+msg.b=4
+msg.a=1
+while True:
+    node.publish('Colorsh',msg) #publish data to node Colorsh
+    sleep(1)

tests/protocoltest.py

@@ -1,3 +1,9 @@
+"""
+This is a script to prove
+rosserial topic negotiation
+and publish
+"""
+
 import machine as m
 import uio
 import struct
@@ -77,6 +83,4 @@ def serializeString(packet):
         uart.write(packetdata)
         uart.write(bytearray(checksumpackdata))
         print('enviado hola')
-        sleep(1)      
-
-        
+        sleep(1)