GHIElectronics.Endpoint.Devices.Network 0.5.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,234 @@
1
+ """Network on Endpoint, by type (Ethernet, WiFi) instead of system
2
+ identifiers (eth0, wlan0) that change with plug order.
3
+
4
+ Enable / Disable are runtime-only and do not touch /config/network.json.
5
+ Get/SetInterfaceSettings read and write that file; agent's boot applier
6
+ honours the enableAtBoot flag per section. Status (addresses, link state,
7
+ DNS, speed) is the standard Python surface (``socket``, ``ipaddress``,
8
+ parsing ``/proc/net/route`` or ``ip``).
9
+
10
+ from GHIElectronics.Endpoint.Devices.Network import NetworkType, NetworkController
11
+
12
+ eth = NetworkController.FromType(NetworkType.Ethernet)
13
+ if eth is not None:
14
+ eth.Enable()
15
+ while not eth.IsConnected:
16
+ time.sleep(0.5)
17
+ print(f"ethernet is {eth.Name}, connected")
18
+ """
19
+
20
+ import ctypes
21
+ import json
22
+ import os
23
+ import tempfile
24
+ from enum import IntEnum
25
+
26
+ from GHIElectronics.Endpoint.Core._native import native
27
+
28
+
29
+ _CONFIG_PATH = "/config/network.json"
30
+ _SECTION_KEYS = {} # populated after NetworkType is defined
31
+
32
+
33
+ class NetworkType(IntEnum):
34
+ """What a network interface is, as the user sees it in network.json."""
35
+
36
+ Ethernet = 0
37
+ Wifi = 1
38
+
39
+
40
+ _SECTION_KEYS[NetworkType.Ethernet] = "ethernet"
41
+ _SECTION_KEYS[NetworkType.Wifi] = "wifi"
42
+
43
+
44
+ class WiFiSecurityType(IntEnum):
45
+ """How a WiFi network authenticates clients."""
46
+
47
+ None_ = 0
48
+ Wpa = 1
49
+ Wpa2 = 2
50
+ Wpa3 = 3
51
+
52
+
53
+ class NetworkInterfaceSettings:
54
+ """Settings for an Ethernet interface. Read with
55
+ :meth:`NetworkController.GetInterfaceSettings` and apply with
56
+ :meth:`NetworkController.SetInterfaceSettings`. For WiFi use
57
+ :class:`WiFiNetworkInterfaceSettings`."""
58
+
59
+ def __init__(self):
60
+ self.IsDhcpEnabled = True
61
+ self.Address = None # str "192.168.1.100" or None
62
+ self.SubnetMask = None # str "255.255.255.0" or None
63
+ self.GatewayAddress = None # str "192.168.1.1" or None
64
+ self.DnsAddresses = None # list[str] or None
65
+ self.MacAddress = None # str "aa:bb:cc:dd:ee:ff" or None
66
+
67
+
68
+ class WiFiNetworkInterfaceSettings(NetworkInterfaceSettings):
69
+ """Settings for a WiFi interface. Adds SSID + password + security
70
+ on top of the common fields."""
71
+
72
+ def __init__(self):
73
+ super().__init__()
74
+ self.Ssid = ""
75
+ self.Password = ""
76
+ self.Security = WiFiSecurityType.Wpa2
77
+
78
+
79
+ class NetworkController:
80
+ """One of the board's network interfaces, by type (Ethernet, WiFi).
81
+ :meth:`FromType` always returns a controller - the controller
82
+ represents the type, not a specific interface. Hardware does not have
83
+ to be present yet; call :meth:`SetInterfaceSettings` to configure,
84
+ then :meth:`Enable`, which modprobes any USB driver needed and brings
85
+ the matching interface up. Use :attr:`IsPresent` to check if hardware
86
+ is currently present."""
87
+
88
+ def __init__(self, type_):
89
+ self.Type = type_
90
+ self._section = _SECTION_KEYS[type_]
91
+
92
+ @staticmethod
93
+ def FromType(type_):
94
+ """The controller for the given type. Always non-null."""
95
+ return NetworkController(type_)
96
+
97
+ @property
98
+ def Name(self):
99
+ """System identifier (eth0, wlan0, ...), or empty string if no
100
+ interface of this type is currently present. Reads live from the
101
+ kernel on every access."""
102
+ return NetworkController.GetName(self.Type)
103
+
104
+ @property
105
+ def IsPresent(self):
106
+ """True if an interface of this type currently exists on the board.
107
+ WiFi stays False until :meth:`Enable` is called at least once
108
+ (that is what modprobes the WiFi driver)."""
109
+ return len(self.Name) > 0
110
+
111
+ @staticmethod
112
+ def GetName(type_):
113
+ """The system identifier (eth0, wlan0, ...) for the first interface
114
+ of the given type, or an empty string if none is present."""
115
+ buffer = ctypes.create_string_buffer(32)
116
+ native.network_get_interface_name(int(type_), buffer, len(buffer))
117
+ return buffer.value.decode("ascii")
118
+
119
+ @property
120
+ def IsEnabled(self):
121
+ """True if the interface is administratively up."""
122
+ result = ctypes.c_int()
123
+ native.network_is_enabled(int(self.Type), native.ref(result))
124
+ return result.value != 0
125
+
126
+ @property
127
+ def IsConnected(self):
128
+ """True if the interface has carrier (cable plugged / associated)
129
+ AND an IPv4 address."""
130
+ result = ctypes.c_int()
131
+ native.network_is_connected(int(self.Type), native.ref(result))
132
+ return result.value != 0
133
+
134
+ def Enable(self):
135
+ """Applies the settings from ``/config/network.json`` to this
136
+ interface synchronously. Runtime only; does not touch the JSON."""
137
+ native.network_enable(int(self.Type))
138
+
139
+ def Disable(self):
140
+ """Stops DHCP and brings the interface down. Runtime only; does
141
+ not touch the JSON."""
142
+ native.network_disable(int(self.Type))
143
+
144
+ def GetInterfaceSettings(self):
145
+ """Reads the current settings for this type from
146
+ ``/config/network.json``. Changes to the returned object do nothing
147
+ until passed back to :meth:`SetInterfaceSettings`."""
148
+ config = _load_config()
149
+ section = config.get(self._section) or {}
150
+
151
+ if self.Type == NetworkType.Wifi:
152
+ s = WiFiNetworkInterfaceSettings()
153
+ s.Ssid = section.get("ssid") or ""
154
+ s.Password = section.get("password") or ""
155
+ s.Security = _parse_security(section.get("security"))
156
+ else:
157
+ s = NetworkInterfaceSettings()
158
+
159
+ s.IsDhcpEnabled = bool(section.get("dhcp", True))
160
+ static = section.get("static") or {}
161
+ s.Address = static.get("ip") or None
162
+ s.SubnetMask = static.get("mask") or None
163
+ s.GatewayAddress = static.get("gateway") or None
164
+ dns = static.get("dns") or []
165
+ s.DnsAddresses = list(dns) if dns else None
166
+ s.MacAddress = section.get("mac") or None
167
+ return s
168
+
169
+ def SetInterfaceSettings(self, settings):
170
+ """Writes the settings to ``/config/network.json`` (persisted
171
+ across reboots). Does NOT apply them to the live interface -
172
+ call :meth:`Enable` for that."""
173
+ if settings is None:
174
+ raise ValueError("settings must not be None")
175
+
176
+ config = _load_config()
177
+ section = config.get(self._section) or {}
178
+
179
+ section["dhcp"] = bool(settings.IsDhcpEnabled)
180
+ section["mac"] = settings.MacAddress
181
+ section["static"] = {
182
+ "ip": settings.Address,
183
+ "mask": settings.SubnetMask,
184
+ "gateway": settings.GatewayAddress,
185
+ "dns": list(settings.DnsAddresses) if settings.DnsAddresses else [],
186
+ }
187
+
188
+ if isinstance(settings, WiFiNetworkInterfaceSettings):
189
+ section["ssid"] = settings.Ssid
190
+ section["password"] = settings.Password
191
+ section["security"] = settings.Security.name.lower().rstrip("_")
192
+
193
+ config[self._section] = section
194
+ _save_config(config)
195
+
196
+
197
+ # ---------------------------------------------------------------------------
198
+
199
+ def _load_config():
200
+ if not os.path.exists(_CONFIG_PATH):
201
+ return {"version": 1}
202
+ try:
203
+ with open(_CONFIG_PATH, "r") as f:
204
+ data = json.load(f)
205
+ return data if isinstance(data, dict) else {"version": 1}
206
+ except (OSError, json.JSONDecodeError):
207
+ return {"version": 1}
208
+
209
+
210
+ def _save_config(config):
211
+ # Atomic write: temp file in same dir then rename
212
+ directory = os.path.dirname(_CONFIG_PATH) or "."
213
+ fd, tmp = tempfile.mkstemp(prefix=".network", suffix=".json.tmp", dir=directory)
214
+ try:
215
+ with os.fdopen(fd, "w") as f:
216
+ json.dump(config, f, indent=2)
217
+ os.replace(tmp, _CONFIG_PATH)
218
+ except Exception:
219
+ try: os.unlink(tmp)
220
+ except OSError: pass
221
+ raise
222
+
223
+
224
+ def _parse_security(value):
225
+ if value is None:
226
+ return WiFiSecurityType.Wpa2
227
+ v = value.lower()
228
+ if v in ("none", "open"):
229
+ return WiFiSecurityType.None_
230
+ if v == "wpa":
231
+ return WiFiSecurityType.Wpa
232
+ if v == "wpa3":
233
+ return WiFiSecurityType.Wpa3
234
+ return WiFiSecurityType.Wpa2
@@ -0,0 +1,20 @@
1
+ Metadata-Version: 2.4
2
+ Name: GHIElectronics.Endpoint.Devices.Network
3
+ Version: 0.5.1
4
+ Summary: Network on GHI Electronics Endpoint: ethernet, WiFi and PC-shared by kind, not by Linux name.
5
+ Author-email: "GHI Electronics, LLC" <support@ghielectronics.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://www.ghielectronics.com/
8
+ Project-URL: Repository, https://github.com/ghi-electronics/Endpoint-Libraries
9
+ Project-URL: Issues, https://github.com/ghi-electronics/Endpoint-Libraries/issues
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Operating System :: POSIX :: Linux
12
+ Requires-Python: >=3.9
13
+ Description-Content-Type: text/markdown
14
+ Requires-Dist: GHIElectronics.Endpoint.Core<0.6,>=0.5.1
15
+
16
+ # GHIElectronics.Endpoint.Devices.Network
17
+
18
+ Network on GHI Electronics Endpoint: ethernet, WiFi and PC-shared by kind, not by Linux name.
19
+
20
+ Part of the [GHI Electronics Endpoint](https://github.com/ghi-electronics/Endpoint-Libraries) libraries. See the repository README for the full package list and getting-started guide.
@@ -0,0 +1,5 @@
1
+ GHIElectronics/Endpoint/Devices/Network/__init__.py,sha256=z9wDkDpgfEiXGVdccKzg4Lan9b_VFoXmZ2d69PBPvf8,8149
2
+ ghielectronics_endpoint_devices_network-0.5.1.dist-info/METADATA,sha256=7PhRQ8Mq1dcE4rjOnHWqAmojT1wGzKiMex0joV3u6II,1049
3
+ ghielectronics_endpoint_devices_network-0.5.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
4
+ ghielectronics_endpoint_devices_network-0.5.1.dist-info/top_level.txt,sha256=NpOZNgd0iquwrRPrTOhUDxc2V9TtNFLv5Z_Dx3YZtIU,15
5
+ ghielectronics_endpoint_devices_network-0.5.1.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+