MagnetoShield Class

class automationshield.MagnetoShield(port: str | None = None)

Bases: BaseShield

Class for Magnetoshield device. Inherits from BaseShield.

The Magnetoshield device is a control experiment using magnetic levitation. The actuator is an electromagnet over which the voltage can be controlled. The electromagnet attracts a permanent magnet placed below the electromagnet. The position of the permanent magnet is estimated using a Hall effect sensor.

Interface:

• Actuator input should be provided in percent by default.

• Potentiometer is provided in percent by default.

• Sensor values are provided in Gauss by default. This class provides an additional method MagnetoShield.magnet_position(), which calculates the distance of the permanent magnet from the electromagnet.

This class does not use the BaseShield.zero_reference attribute.

Parameters:

port (str | None) – Port on which the Arduino is connected, defaults to None.

script: str = 'magnetoshield'

Name of the script directory in which the .ino file for the specific shield is located.

shield_id: str = 'MG'

ID assigned to shield. This is used to check whether the correct firmware is installed on the Arduino.

actuator_bits: int = 12

Number of bits used for actuator.

potentiometer_bits: int = 10

Number of bits used for potentiometer.

sensor_bits: int = 10

Number of bits used for sensor.

class PlotInfo

Bases: PlotInfo

sensor_unit: str = 'mm'

Sets the unit on the axis label of the output plot.

sensor_type: str = 'Height'

Sets the name of the axis of the output plot.

sensor_min: float = 12

Sets to lower bound of the sensor value. This is used to set up the LivePlotter.

sensor_max: float = 17

Sets the upper bound of the sensor value. This is used to set up the LivePlotter.

emagnet_height: int = 20

Height of the electromagnet above ground in mm.

magnet_low: int = 3

Top of the magnet from ground - distance from Hall element in mm when the magnet is at the bottom of the tube.

magnet_high: int = 8

Top of the magnet from ground - distance from Hall element in mm when the magnet is at the top of the tube.

default_p1: float = 3.2331

Default value for calculating the magnet position. See MagnetoShield.magnet_position().

default_p2: float = 0.220571

Default value for calculating the magnet position. See MagnetoShield.magnet_position().

convert_sensor_reading(sensor: int) → float

Converts the n-bit sensor reading of the Hall effect sensor to Gauss. The constants in this method are for release 4 of the MagnetoShield. Conversion is done using

\[B = \left(2.5 - s \cdot \frac{3.3}{2^{10} - 1}\right) \cdot 800\]

The sensor value \(s\) is scaled with the ratio of the ADC reference voltage (\(3.3\) (\(V\))) over the AD converter resolution (\(10\) bits, i.e. \(1023\)). The \(2.5\) (\(V\)) bias for zero magnetic flux is subtracted and the result is scaled with the sensitivity of the Hall effect sensor (\(1.25 \frac{mV}{G} = 800 \frac{G}{V}\))

Parameters:

sensor (int) – Raw sensor value.

Returns:

Sensor value in Gauss.

Return type:

float

calibrate_sensor_reading(sensor: int) → int

Return sensor value as is. No calibration is performed.

Parameters:

sensor (int) – Raw sensor value.

Returns:

Raw sensor value.

Return type:

int

property p1: float

Return \(p_1\) constant calculated during calibration. If not available, return default_p1.

Returns:

\(p_1\) constant.

property p2: float

Return :math`p_2` constant calculated during calibration. If not available, return default_p2.

Returns:

\(p_2\) constant.

calibrate()

Perform sensor calibration for conversion from Gauss to magnet distance from electromagnet. The sensor values are read in the lowest and highest magnet position, \(s_{0}\) and \(s_{1}\) respectively. The constants \(p_1\) and \(p2\) are calculated as follows:

\[\begin{split}p_2 &= \frac{ \log{ \left( z_{e} - z_{0} \right) } - \log{ \left( z_{e} - z_{1} \right) } } { \log{ s_{0} } - \log{ s_{1} } } \\ p_1 &= \frac{ z_{e} - z_{1} } { \left( s_{1} \right)^{p_2} }\end{split}\]

\(z_{e}\), \(z_{0}\) and \(z_{1}\) correspond to emagnet_height, magnet_low and magnet_high, respectively.

magnet_position(sensor: float) → float

Calculate magnet distance from electromagnet using

\[y = p_1 \cdot B^{p_2}\]

where \(B\) is the magnetic flux density in Gauss. \(p_1\) and \(p_2\) are constants which are calculated in calibrate().

The distance can vary between approximately \(12 mm\) and \(17 mm\).

Parameters:

sensor (float) – Sensor value in Gauss.

Returns:

Magnet distance from electromagnet.

Return type:

float