Remote Device¶
AddressInfo¶
ConfigProfile¶
-
class
canlib.kvrlib.ConfigProfile(device, profile_number)[source]¶ A configuration profile of a remote-capable device
The active profile for a
RemoteDevice,rdev, is accessed with:profile = rdev.active_profile
Other profiles are accessed with
profiles:first = rdev.profiles[0]
See the documentation for
RemoteDevicefor more information on how to getConfigProfileobjects.The specific configuration of a profile can be read:
xml_string = profile.read()
And it can also be written back:
profile.write(xml_string)
The password used by this object is taken from its parent
RemoteDeviceobject. See that documentation for how to set the password.-
XML_BUFFER_SIZE= 2046¶
-
channel_number¶ The CANlib channel number used to communicate with the device
Type: int
-
clear()[source]¶ Clear the configuration
This will also clear any previously set device password.
Note
This method requires the parent
RemoteDeviceto have the correct password.
-
info¶ A simplified version of the configuration
It is not necessary to know the configuration password to access this information. Note that the partial XML data returned is not enough to reconfigure a device.
Type: str
-
password¶ The password used to communicate with the device
Type: str
-
read()[source]¶ Read the configuration
Returns either an XML string, or
Noneif there is no configuration.Note that
ConfigProfile.writecan handleNone; in other words:xml = profile.read() # Do anything, including writing new configurations ... profile.write(xml)
Will always work even if
xmlisNone. This would mean that the profile originally had an empty configuration, and it will once again have an empty configuration at the end.Note
This method requires the parent
RemoteDeviceto have the correct password.
-
write(xml)[source]¶ Write the configuration area
This function takes as its single argument either an xml string that will be written to this profile, or
Nonein which case the configuration will be cleared.Note
This method requires the parent
RemoteDeviceto have the correct password.
-
ConnectionStatus¶
-
class
canlib.kvrlib.ConnectionStatus(state, tx_rate, rx_rate, channel_number, rssi, tx_power)¶ -
channel_number¶ Alias for field number 3
-
rssi¶ Alias for field number 4
-
rx_rate¶ Alias for field number 2
-
state¶ Alias for field number 0
-
tx_power¶ Alias for field number 5
-
tx_rate¶ Alias for field number 1
-
ConnectionTestResult¶
ConnectionTest¶
-
class
canlib.kvrlib.ConnectionTest(config_handle)[source]¶ A connection test for a specific device
A connection test for a
RemoteDevice,rdev, is created by:test = rdev.connection_test()
While a connection test is running, the device will connect and start pinging itself to measure round-trip time (RTT) and Receive Signal Strength Indicator (RSSI).
A
ConnectionTestis started withConnectionTest.startand stopped withConnectionTest.stop, after which its results are retrieved byConnectionTest.results. If it is acceptable to block while the test is running, these three calls can be combined intoConnectionTest.run:results = test.run(duration=10) print(results)
Connection tests are automatically closed when garbage-collected, but they can also be closed manually with
ConnectionTest.close.-
results(maxresults=20)[source]¶ Get the results from a connection test
The test must have been running for any results to be available.
This function returns a
ConnectionTestResult, which is a namedtuple of(rssi, rtt). Bothrssiandrttare tuples containing a number of individual results for RSSI and RTT.Parameters: maxresults ( int) – The maximum number of rssi and rtt numbers to return. The returnedrssiandrttwill be tuples with this long or the number of results available long, whichever is shortest.
-
run(duration, maxresults=20)[source]¶ Run a connection test and return its results.
This function calls
ConnectionTest.start, then blocks fordurationseconds, then callsConnectionTest.stopbefore finally returning theConnectionTestResultfromConnectionTest.results.Parameters: - duration (
int) – Seconds to run the test for. - maxresults (
int) – Passed toConnectionTest.resultsasmaxlen.
- duration (
-
openDevice()¶
-
canlib.kvrlib.openDevice(channel_number, password='', validate_password=False)[source]¶ Create a
RemoteDeviceobject bound to a channel numberParameters: - channel_number (
int) – CANlib channel number of the device to open - password (
str) – Password of the device, if any - validate_password (
bool) – Whether the password should be validated (defaults toFalse).
This function checks that a remote-capable device is currently connection on the channel
channel_number. Ifvalidate_passwordisTrue, it also checks that the password supplied is correct. If any of these checks fail, aValueErrorwill be raised.- channel_number (
RemoteDevice¶
-
class
canlib.kvrlib.RemoteDevice(channel_number, password)[source]¶ A remote-capable Kvaser device
This class is normally instantiated with
openDevice:rdev = kvrlib.openDevice(CHANNEL_NUMBER)
Once this is done, the currently active profile can be accessed:
active = rdev.active_profile
All profiles, including the active one, are
ConfigProfileobjects, see that documentation for all the operations available for profile objects.The full list of profiles a device has can be inspected using
rdev.profiles. This is aRemoteDevice.ProfileListobject, which works much like a list:# The profile list can be indexed first = rdev.profiles[0] # We can check if a configuration belongs to this device with 'in' assert first in rdev.profiles # The length of the profile list is the number of profiles num_profiles = len(rdev.profiles) # Using the number of profiles, we can get the last one last = rdev.profiles[num_profiles - 1] # But negative indexes also work and are a better way of getting # the last profile last = rdev.profiles[-1] # You can also iterate over all profiles for profile in rdev.profiles: ...
RemoteDevicealso lets you access a variety of information about the specific device, as well as the ability to do a WLAN scan withRemoteDevice.wlan_scan.If the device is password protected, that password can be passed to
openDevice:protected_device = kvrlib.openDevice(0, password="Once upon a playground rainy")
After the object is created, the password is available as:
password = protected_device.password
The password can be changed with:
protected_device.password = "Wolves without teeth"
The reason the password is stored as clear-text is because it must be supplied to the underlying library each time an operation is done using this and related classes. This also means that the password is only validated, and required, when one of the functions requiring a password is called.
If the device is not password-protected, the password should be an empty string:
unprotected_device = kvrlib.openDevice(1) assert unprotected_device.password == ''
-
class
ProfileList(channel_number)[source]¶ The available profiles in a remote-capable device
This is the type of
RemoteDevice.profiles. It implements the following:len(profiles)profile in profilesprofile[index]
-
active_profile¶ The currently active profile
Activating another profile is done by assigning this attribute to another profile:
new_profile = remote_device.profiles[index] remote_device.active_profile = new_profile
The value assigned to this property must be a
ConfigProfilethat belongs to this device, i.e. the following must beTrue:new_profile in remote_device.profiles
Type: ConfigProfile
-
address_info¶ Information about network address settings
Note
Accessing this attribute requires the correct password be set on the object.
Type: AddressInfo
-
connection_status¶ Connection status information
The returned tuple is a
(state, tx_rate, rx_rate, channel, rssi, tx_power)namedtuple of:state(NetworkState): Network connection statetx_rate(int): Transmit rate in kbit/srx_rate(int): Receive rate in kbit/schannel(int): Channelrssi(int): Receive Signal Strength Indicatortx_power(int): Transmit power level in dB
Note
Accessing this attribute requires the correct password be set on the object.
Type: ConnectionStatus
-
connection_test()[source]¶ Creates a connection test for this device
Returns: ConnectionTestSee the documentation of
ConnectionTestfor more information.Note
Accessing this attribute requires the correct password be set on the object.
-
hostname¶ Device’s hostname
Note
Accessing this attribute requires the correct password be set on the object.
Type: str
-
password_valid()[source]¶ Checks whether the password set is valid
Returns: bool–Trueif the password is valid,Falseotherwise.
-
wlan_scan(active=False, bss_type=<BasicServiceSet.ANY: 2>, domain=<RegulatoryDomain.WORLD: 3>)[source]¶ Creates and starts a wlan scan for this device
Returns: WlanScanSee the documentation of
WlanScanfor more information.Note
Accessing this attribute requires the correct password be set on the object.
-
class
WlanScan¶
-
class
canlib.kvrlib.WlanScan(config_handle)[source]¶ A wlan scan for this device
The device starts scanning as soon as this object is created by
RemoteDevice.wlan_scan:scan = rdev.wlan_scan()
When calling
RemoteDevice.wlan_scan, you can also specify whether the scan should be an active one, the Basic Service Set (bss) to use, and the regulatory domain:scan = rdev.wlan_scan( active=True, bss=kvrlib.BasicServiceSet.INFRASTRUCTURE, domain=kvrlib.RegulatoryDomain.EUROPE_ETSI, )
Results from the scan are retrieved by iterating over the
WlanScanobject:- for result in scan:
- print(result)
When getting the next result, the code will block until a new result is available or until no more results are available, in which case the iteration stops.
Wlan scans are automatically closed when garbage-collected, but they can also be closed manually with
WlanScan.close.
WlanScanResult¶
-
class
canlib.kvrlib.WlanScanResult(rssi, channel_number, mac, bss_type, ssid, security_text)¶ -
bss_type¶ Alias for field number 3
-
channel_number¶ Alias for field number 1
-
mac¶ Alias for field number 2
-
rssi¶ Alias for field number 0
-
security_text¶ Alias for field number 5
-
ssid¶ Alias for field number 4
-