Docs: Refactor icsneopy examples

CMakeLists.txt

@@ -355,8 +355,9 @@ if(LIBICSNEO_ENABLE_DXX)
 	include(FetchContent)
 	FetchContent_Declare(libredxx
 		GIT_REPOSITORY https://github.com/Zeranoe/libredxx.git
-		GIT_TAG 2b7932fe7f2fc006ef269c7a72595f3940178a10
+		GIT_TAG 1e3798655a6376d2085ef8d0267c035ae78c6446
 	)
+	set(LIBREDXX_DISABLE_INSTALL ON)
 	FetchContent_MakeAvailable(libredxx)
 endif()
 

docs/icsneopy/can_getting_started.rst

@@ -0,0 +1,56 @@
+===================
+CAN Getting Started
+===================
+
+Prerequisites
+=============
+
+- Python 3.8 or higher
+- icsneopy library installed
+- CAN hardware device connected
+
+:download:`Download complete example <../../examples/python/can/can_complete_example.py>`
+
+Basic Setup
+===========
+
+1. Import the library and discover devices:
+
+.. literalinclude:: ../../examples/python/can/can_complete_example.py
+   :language: python
+   :lines: 11-19
+
+2. Configure and open the device:
+
+.. literalinclude:: ../../examples/python/can/can_complete_example.py
+   :language: python
+   :lines: 22-37
+
+Transmitting CAN Frames
+========================
+
+.. literalinclude:: ../../examples/python/can/can_complete_example.py
+   :language: python
+   :lines: 40-53
+
+Receiving CAN Frames
+=====================
+
+.. literalinclude:: ../../examples/python/can/can_complete_example.py
+   :language: python
+   :lines: 56-72
+
+Cleanup and Resource Management
+===============================
+
+.. literalinclude:: ../../examples/python/can/can_complete_example.py
+   :language: python
+   :lines: 75-79
+
+Complete Example with Error Handling
+====================================
+
+.. literalinclude:: ../../examples/python/can/can_complete_example.py
+   :language: python
+   :lines: 82-125
+

docs/icsneopy/ethernet_getting_started.rst

@@ -0,0 +1,70 @@
+=========================
+Ethernet Getting Started
+=========================
+
+This guide provides basic instructions for working with Ethernet devices using the icsneopy library.
+
+Prerequisites
+=============
+
+- Python 3.8 or higher
+- icsneopy library installed
+- Intrepid Control Systems Device
+
+:download:`Download complete example <../../examples/python/ethernet/ethernet_complete_example.py>`
+
+Opening the Device
+==================
+
+To begin working with an Ethernet device, you must first discover, open, and bring it online:
+
+.. literalinclude:: ../../examples/python/ethernet/ethernet_complete_example.py
+   :language: python
+   :lines: 11-37
+
+Transmitting Ethernet Frames
+=============================
+
+Transmit Ethernet frames using the EthernetMessage class:
+
+.. literalinclude:: ../../examples/python/ethernet/ethernet_complete_example.py
+   :language: python
+   :lines: 61-78
+
+Monitoring Ethernet Status
+==========================
+
+Monitor Ethernet link status changes using message callbacks:
+
+.. literalinclude:: ../../examples/python/ethernet/ethernet_complete_example.py
+   :language: python
+   :lines: 39-40
+
+DoIP Ethernet Activation Control
+================================
+
+Diagnostics over Internet Protocol (DoIP) can be controlled through digital I/O pins:
+
+:download:`Download DoIP example <../../examples/python/doip/doip_activation_control.py>`
+
+.. literalinclude:: ../../examples/python/doip/doip_activation_control.py
+   :language: python
+   :lines: 28-44
+
+Network Configuration Reference
+===============================
+
+Standard Ethernet network identifiers:
+
+- ``icsneopy.Network.NetID.ETHERNET_01`` - Standard Ethernet Port 1
+
+Automotive Ethernet network identifiers:
+
+- ``icsneopy.Network.NetID.AE_01`` - Automotive Ethernet Port 1
+
+Complete Example with Resource Management
+=========================================
+
+.. literalinclude:: ../../examples/python/ethernet/ethernet_complete_example.py
+   :language: python
+   :lines: 86-127

docs/icsneopy/examples.rst

@@ -3,128 +3,66 @@ Python Examples
 ===============
 
 Transmit CAN frames on DW CAN 01
-============================
+=================================
 
-.. code-block:: python
+:download:`Download example <../../examples/python/can/can_transmit_basic.py>`
 
-   import icsneopy
+.. literalinclude:: ../../examples/python/can/can_transmit_basic.py
-
+   :language: python
-   devices: list[icsneopy.Device] = icsneopy.find_all_devices()
-
-   # grab the first/only device found
-   device: icsneopy.Device = devices[0]
-
-   message = icsneopy.CANMessage()
-   message.network = icsneopy.Network(icsneopy.Network.NetID.DWCAN_01)
-   message.arbid = 0x56
-   message.data = (0x11, 0x22, 0x33)
-
-   device.open()
-
-   device.go_online()
-
-   device.transmit(message)
      
 Receive CAN frames on DW CAN 01
-===========================
+================================
 
-.. code-block:: python
+:download:`Download example <../../examples/python/can/can_receive_basic.py>`
 
-   import icsneopy
+.. literalinclude:: ../../examples/python/can/can_receive_basic.py
-   import time
+   :language: python
 
-   devices: list[icsneopy.Device] = icsneopy.find_all_devices()
+Complete CAN Example
+====================
 
-   # grab the first/only device found
+:download:`Download example <../../examples/python/can/can_complete_example.py>`
-   device: icsneopy.Device = devices[0]
 
-   def on_message(message: icsneopy.CANMessage):
+.. literalinclude:: ../../examples/python/can/can_complete_example.py
-       print(message.arbid, message.data)
+   :language: python
-   message_filter = icsneopy.MessageFilter(icsneopy.Network.NetID.DWCAN_01)
-   callback = icsneopy.MessageCallback(on_message, message_filter)
 
-   device.add_message_callback(callback)
 
-   device.open()
+Transmit Ethernet frames on Ethernet 01
-   device.go_online()
+========================================
 
-   # rx for 10s
+:download:`Download example <../../examples/python/ethernet/ethernet_transmit_basic.py>`
-   time.sleep(10)
 
+.. literalinclude:: ../../examples/python/ethernet/ethernet_transmit_basic.py
+   :language: python
 
 Monitor Ethernet Status
 =======================
 
-.. code-block:: python
+:download:`Download example <../../examples/python/ethernet/ethernet_monitor_status.py>`
 
-   import icsneopy
+.. literalinclude:: ../../examples/python/ethernet/ethernet_monitor_status.py
-   import time
+   :language: python
 
-   def main():
+TC10 Power Management
-      devices = icsneopy.find_all_devices()
+=====================
-      if len(devices) == 0:
-         print("error: no devices found")
-         return False
-
-      device = devices[0]
-      print(f"info: monitoring Ethernet status on {device}")
-
-      def on_message(message):
-         print(f"info: network: {message.network}, state: {message.state}, speed: {message.speed}, duplex: {message.duplex}, mode: {message.mode}")
-
-      filter = icsneopy.MessageFilter(icsneopy.Message.Type.EthernetStatus)
-      callback = icsneopy.MessageCallback(on_message, filter)
-      device.add_message_callback(callback)
-
-      if not device.open():
-         print("error: unable to open device")
-         return False
-
-      if not device.go_online():
-         print("error: unable to go online")
-         return False
-
-      while True:
-         time.sleep(1)
-
-   main()
-
-TC10
-====
 
 :download:`Download example <../../examples/python/tc10/tc10.py>`
 
 .. literalinclude:: ../../examples/python/tc10/tc10.py
+   :language: python
 
 DoIP Ethernet Activation
 ========================
 
-.. code-block:: python
+:download:`Download example <../../examples/python/doip/doip_activation_control.py>`
 
-   import icsneopy
+.. literalinclude:: ../../examples/python/doip/doip_activation_control.py
-   import time
+   :language: python
 
-   devs = icsneopy.find_all_devices()
+Complete Ethernet Example
+=========================
 
-   dev = devs[0]
+:download:`Download example <../../examples/python/ethernet/ethernet_complete_example.py>`
 
-   dev.open()
+.. literalinclude:: ../../examples/python/ethernet/ethernet_complete_example.py
-
+   :language: python
-   # the device must be online for digital I/O
-   dev.go_online()
-
-   print(f"initial state: {dev.get_digital_io(icsneopy.IO.EthernetActivation, 1)}")
-
-   dev.set_digital_io(icsneopy.IO.EthernetActivation, 1, True)
-
-   print(f"after setting to true: {dev.get_digital_io(icsneopy.IO.EthernetActivation, 1)}")
-
-   # allow for observing the change
-   time.sleep(2)
-
-   dev.set_digital_io(icsneopy.IO.EthernetActivation, 1, False)
-
-   print(f"after setting to false: {dev.get_digital_io(icsneopy.IO.EthernetActivation, 1)}")
-
-   # allow for observing the change
-   time.sleep(2)

docs/icsneopy/index.rst

@@ -5,6 +5,8 @@ icsneopy
 .. toctree::
    :maxdepth: 2
 
+   can_getting_started
+   ethernet_getting_started
    examples
    api
    radepsilon

examples/python/can/can_complete_example.py

@@ -0,0 +1,125 @@
+"""
+Complete CAN example using icsneopy library.
+
+Demonstrates device setup and CAN frame transmission/reception.
+"""
+
+import icsneopy
+import time
+
+
+def setup_device():
+	"""Initialize CAN device."""
+	devices = icsneopy.find_all_devices()
+	if not devices:
+		raise RuntimeError("No devices found")
+
+	device = devices[0]
+	print(f"Using device: {device}")
+	return device
+
+
+def open_device(device):
+	"""Open device connection."""
+	try:
+		if not device.open():
+			raise RuntimeError("Failed to open device")
+
+		if not device.go_online():
+			device.close()
+			raise RuntimeError("Failed to go online")
+
+		print("Device initialized successfully")
+		return True
+
+	except Exception as e:
+		print(f"Device setup failed: {e}")
+		return False
+
+
+def transmit_can_frame(device, arbid, data):
+	"""Transmit a CAN frame."""
+	frame = icsneopy.CANMessage()
+	frame.network = icsneopy.Network(icsneopy.Network.NetID.DWCAN_01)
+	frame.arbid = arbid
+	frame.data = data
+
+	success = device.transmit(frame)
+	if success:
+		print(f"Frame transmitted: ID=0x{arbid:03X}, Data={list(data)}")
+	else:
+		print(f"Failed to transmit frame ID=0x{arbid:03X}")
+
+	return success
+
+
+def setup_can_reception(device):
+	"""Configure CAN frame reception with callback."""
+	frame_count = 0
+
+	def frame_handler(frame):
+		nonlocal frame_count
+		frame_count += 1
+		print(f"[RX {frame_count}] ID: 0x{frame.arbid:03X}, "
+			  f"Data: {[hex(b) for b in frame.data]}, "
+			  f"Length: {len(frame.data)}")
+
+	frame_filter = icsneopy.MessageFilter(icsneopy.Network.NetID.DWCAN_01)
+	callback = icsneopy.MessageCallback(frame_handler, frame_filter)
+	device.add_message_callback(callback)
+
+	print("CAN frame reception configured")
+	return 0
+
+
+def cleanup_device(device):
+	"""Close device connection."""
+	if device:
+		device.close()
+		print("Device connection closed")
+
+
+def main():
+	"""Complete CAN example with proper error handling."""
+	device = None
+
+	try:
+		# Setup device
+		device = setup_device()
+
+		# Open device
+		if not open_device(device):
+			raise RuntimeError("Failed to initialize device")
+
+		# Setup frame reception
+		setup_can_reception(device)
+
+		# Transmit test frames
+		test_frames = [
+			(0x123, (0x01, 0x02, 0x03, 0x04)),
+			(0x456, (0x05, 0x06, 0x07, 0x08)),
+			(0x789, (0x09, 0x0A, 0x0B, 0x0C))
+		]
+
+		for arbid, data in test_frames:
+			transmit_result = transmit_can_frame(device, arbid, data)
+			if not transmit_result:
+				print(f"Warning: Failed to transmit frame ID=0x{arbid:03X}")
+			time.sleep(0.1)
+
+		# Listen for responses
+		print("Listening for CAN frames for 5 seconds...")
+		time.sleep(5)
+
+	except Exception as e:
+		print(f"Error: {e}")
+		return 1
+
+	finally:
+		cleanup_device(device)
+
+	return 0
+
+
+if __name__ == "__main__":
+	main()

examples/python/can/can_receive_basic.py

@@ -0,0 +1,47 @@
+"""
+Basic CAN frame reception example using icsneopy library.
+
+Demonstrates how to receive CAN frames on DW CAN 01 using callback handlers.
+"""
+
+import icsneopy
+import time
+
+
+def receive_can_frames():
+	"""Receive CAN frames with callback handling."""
+	devices = icsneopy.find_all_devices()
+	if not devices:
+		raise RuntimeError("No devices found")
+
+	device = devices[0]
+	frame_count = 0
+
+	def on_frame(frame):
+		nonlocal frame_count
+		frame_count += 1
+		print(f"[RX {frame_count}] ID: 0x{frame.arbid:03X}, "
+			  f"Data: {[hex(b) for b in frame.data]}")
+
+	frame_filter = icsneopy.MessageFilter(icsneopy.Network.NetID.DWCAN_01)
+	callback = icsneopy.MessageCallback(on_frame, frame_filter)
+
+	try:
+		if not device.open():
+			raise RuntimeError("Failed to open device")
+
+		if not device.go_online():
+			raise RuntimeError("Failed to go online")
+
+		device.add_message_callback(callback)
+		print("Listening for CAN frames for 10 seconds...")
+		time.sleep(10)
+
+		print(f"Total frames received: {frame_count}")
+
+	finally:
+		device.close()
+
+
+if __name__ == "__main__":
+	receive_can_frames()

examples/python/can/can_transmit_basic.py

@@ -0,0 +1,41 @@
+"""
+Basic CAN frame transmission example using icsneopy library.
+
+Demonstrates how to transmit CAN frames on DW CAN 01.
+"""
+
+import icsneopy
+
+
+def transmit_can_frame():
+	"""Transmit a CAN frame."""
+	devices = icsneopy.find_all_devices()
+	if not devices:
+		raise RuntimeError("No devices found")
+
+	device = devices[0]
+
+	try:
+		if not device.open():
+			raise RuntimeError("Failed to open device")
+
+		if not device.go_online():
+			raise RuntimeError("Failed to go online")
+
+		frame = icsneopy.CANMessage()
+		frame.network = icsneopy.Network(icsneopy.Network.NetID.DWCAN_01)
+		frame.arbid = 0x123
+		frame.data = (0x01, 0x02, 0x03, 0x04)
+
+		success = device.transmit(frame)
+		if success:
+			print(f"Frame transmitted: ID=0x{frame.arbid:03X}")
+		else:
+			print("Failed to transmit frame")
+
+	finally:
+		device.close()
+
+
+if __name__ == "__main__":
+	transmit_can_frame()

examples/python/doip/doip_activation_control.py

@@ -0,0 +1,53 @@
+"""
+DoIP activation control example using icsneopy library.
+
+Demonstrates DoIP (Diagnostics over Internet Protocol) Ethernet activation
+control with comprehensive error handling and state validation.
+"""
+
+import icsneopy
+import time
+
+
+def doip_activation_demo():
+	"""Demonstrate DoIP Ethernet activation control with error handling."""
+	devices = icsneopy.find_all_devices()
+	if not devices:
+		raise RuntimeError("No devices found")
+
+	device = devices[0]
+	print(f"Using {device} for DoIP activation control")
+
+	try:
+		if not device.open():
+			raise RuntimeError("Failed to open device")
+
+		if not device.go_online():
+			raise RuntimeError("Failed to go online")
+
+		initial_state = device.get_digital_io(icsneopy.IO.EthernetActivation, 1)
+		print(f"Initial DoIP activation state: {initial_state}")
+
+		print("Activating DoIP Ethernet...")
+		device.set_digital_io(icsneopy.IO.EthernetActivation, 1, True)
+		time.sleep(1)
+
+		active_state = device.get_digital_io(icsneopy.IO.EthernetActivation, 1)
+		print(f"DoIP activated: {active_state}")
+		time.sleep(2)
+
+		print("Deactivating DoIP Ethernet...")
+		device.set_digital_io(icsneopy.IO.EthernetActivation, 1, False)
+		time.sleep(1)
+
+		final_state = device.get_digital_io(icsneopy.IO.EthernetActivation, 1)
+		print(f"DoIP deactivated: {final_state}")
+
+	except Exception as e:
+		print(f"DoIP control error: {e}")
+	finally:
+		device.close()
+
+
+if __name__ == "__main__":
+	doip_activation_demo()

examples/python/ethernet/ethernet_complete_example.py

@@ -0,0 +1,127 @@
+"""
+Complete Ethernet example using icsneopy library.
+
+Demonstrates device setup and Ethernet frame transmission/reception.
+"""
+
+import icsneopy
+import time
+
+
+def setup_device():
+	"""Initialize Ethernet device."""
+	devices = icsneopy.find_all_devices()
+	if not devices:
+		raise RuntimeError("No devices found")
+
+	device = devices[0]
+	print(f"Using device: {device}")
+	return device
+
+
+def open_device(device):
+	"""Open device connection."""
+	try:
+		if not device.open():
+			raise RuntimeError("Failed to open device")
+
+		if not device.go_online():
+			device.close()
+			raise RuntimeError("Failed to go online")
+
+		print("Device initialized successfully")
+		return True
+
+	except Exception as e:
+		print(f"Device setup failed: {e}")
+		return False
+
+def on_status_message(message):
+	print(f"info: network: {message.network}, state: {message.state}, speed: {message.speed}, duplex: {message.duplex}, mode: {message.mode}")
+	
+
+def setup_ethernet_reception(device):
+	"""Configure Ethernet frame reception with callback."""
+	frame_count = 0
+
+	def frame_handler(frame):
+		nonlocal frame_count
+		frame_count += 1
+		print(f"[RX {frame_count}], "
+			  f"Data: {[hex(b) for b in frame.data]}, "
+			  f"Length: {len(frame.data)}")
+	frame_filter = icsneopy.MessageFilter(icsneopy.Network.NetID.ETHERNET_01)
+	callback = icsneopy.MessageCallback(frame_handler, frame_filter)
+	device.add_message_callback(callback)
+
+	print("CAN frame reception configured")
+	return 0
+
+
+def transmit_ethernet_frame(device):
+	"""Transmit an Ethernet frame."""
+	frame = icsneopy.EthernetMessage()
+	frame.network = icsneopy.Network(icsneopy.Network.NetID.ETHERNET_01)
+	frame.data = [
+		0x00, 0xFC, 0x70, 0x00, 0x01, 0x02,
+		0x00, 0xFC, 0x70, 0x00, 0x01, 0x01,
+		0x08, 0x00,
+		0x01, 0xC5, 0x01, 0xC5
+	]
+
+	success = device.transmit(frame)
+	if success:
+		print("Frame transmitted successfully")
+	else:
+		print("Failed to transmit frame")
+
+	return success
+
+def cleanup_device(device):
+	"""Close device connection."""
+	if device:
+		device.close()
+		print("Device connection closed")
+
+def main():
+	"""Complete Ethernet example"""
+	device = None
+
+	try:
+		# Initialize device
+		device = setup_device()
+
+		# Open device
+		if not open_device(device):
+			raise RuntimeError("Failed to initialize device")
+		
+		filter = icsneopy.MessageFilter(icsneopy.Message.Type.EthernetStatus)
+		status_callback = icsneopy.MessageCallback(on_status_message, filter)
+		device.add_message_callback(status_callback)
+
+		#Setup Ethernet Callback
+		setup_ethernet_reception(device)
+
+		# Transmit an Ethernet frame
+		transmit_result = transmit_ethernet_frame(device)
+		if not transmit_result:
+			print("Warning: Failed to transmit frame")
+
+		# Monitor for a period
+		print("Monitoring for 10 seconds...")
+		time.sleep(10)
+
+		print(f"Monitoring completed.")
+
+	except Exception as e:
+		print(f"Error: {e}")
+		return 1
+
+	finally:
+		cleanup_device(device)
+
+	return 0
+
+
+if __name__ == "__main__":
+	main()

examples/python/ethernet/ethernet_monitor_status.py

@@ -0,0 +1,37 @@
+"""
+Ethernet status monitoring example using icsneopy library.
+
+Demonstrates how to monitor Ethernet link status changes.
+"""
+
+import icsneopy
+import time
+
+def main():
+   devices = icsneopy.find_all_devices()
+   if len(devices) == 0:
+      print("error: no devices found")
+      return False
+
+   device = devices[0]
+   print(f"info: monitoring Ethernet status on {device}")
+
+   def on_message(message):
+      print(f"info: network: {message.network}, state: {message.state}, speed: {message.speed}, duplex: {message.duplex}, mode: {message.mode}")
+
+   filter = icsneopy.MessageFilter(icsneopy.Message.Type.EthernetStatus)
+   callback = icsneopy.MessageCallback(on_message, filter)
+   device.add_message_callback(callback)
+
+   if not device.open():
+      print("error: unable to open device")
+      return False
+
+   if not device.go_online():
+      print("error: unable to go online")
+      return False
+
+   while True:
+      time.sleep(1)
+
+main()

examples/python/ethernet/ethernet_transmit_basic.py

@@ -0,0 +1,45 @@
+"""
+Basic Ethernet frame transmission example using icsneopy library.
+
+Demonstrates how to transmit Ethernet frames on Ethernet 01.
+"""
+
+import icsneopy
+
+
+def transmit_ethernet_frame():
+	"""Transmit an Ethernet frame."""
+	devices = icsneopy.find_all_devices()
+	if not devices:
+		raise RuntimeError("No devices found")
+
+	device = devices[0]
+
+	try:
+		if not device.open():
+			raise RuntimeError("Failed to open device")
+
+		if not device.go_online():
+			raise RuntimeError("Failed to go online")
+
+		frame = icsneopy.EthernetMessage()
+		frame.network = icsneopy.Network(icsneopy.Network.NetID.ETHERNET_01)
+		frame.data = [
+			0x00, 0xFC, 0x70, 0x00, 0x01, 0x02,
+			0x00, 0xFC, 0x70, 0x00, 0x01, 0x01,
+			0x08, 0x00,
+			0x01, 0xC5, 0x01, 0xC5
+		]
+
+		success = device.transmit(frame)
+		if success:
+			print("Frame transmitted successfully")
+		else:
+			print("Failed to transmit frame")
+
+	finally:
+		device.close()
+
+
+if __name__ == "__main__":
+	transmit_ethernet_frame()