.. module:: fourzerobox_lib *************** 4ZeroBox Module *************** This module contains the driver for enabling and handling all 4ZeroBox onboard features. The 4ZeroBox class permits an easier access to the internal peripherals and exposes all functionalities in simple function calls. .. warning:: this library is using the Zerynth *conditional compilation* feature. This means that some of the methods documented below must be explicitly enabled in a separate configuration file called `project.yml` (or using the Zerynth Studio configuration browser). Here Below a list of configurable defines for this library: Example: :: # project.yml config: # enable ethernet connection NETWORK_ETH: null # enable wifi connection NETWORK_WIFI: true # enable gsm connection NETWORK_GSM: true # enable ADC 0-10v/4-20mA peripheral ADC_010_420: null # enable ADC resistive peripheral ADC_RESISTIVE: null # enable ADC current peripheral ADC_CURRENT: null # enable can peripheral CAN_ENABLE: null # enable RS485 peripheral RS485_ENABLE: null # enable RS232 peripheral RS232_ENABLE: null # enable SD Card SDCARD_ENABLED: null # enable DEBUG for fourzerobox DEBUG_FZB: null .. class:: FourZeroBox(i2c_clk=400000, spi_clk=1000000) Initialize the class specifying what features must be enabled and configuring the clock speed of I2C and SPI protocols. :param i2c_clk: Clock for connected I2C devices, in Hz. (D=400000) :param spi_clk: Clock for connected SPI devices, in Hz. (D=1000000) .. method:: config_adc_010_420(ch, pga, sps) This method configure one of the four 0-10V/4-20mA ADC channels (chosen using the `ch` parameter). :param ch: Chose the channel to be configured (can be 1, 2, 3, 4). :param pga: Set the PGA Gain. :param sps: Set the samples-per-second data rate. .. method:: set_conversion_010_420(ch, y_min, y_max, offset=0, under_x=None, over_x=None) Set the conversion method to be applied for the data read from the 0-10V/4-20mA ADC. The conversion scale can be configured using the `y_min` and `y_max` parameters, and optionally it can also be set an `offset` and tresholds for the input data. :param ch: Chose the channel to be configured (can be 1, 2, 3, 4). :param y_min: Set the minimum value for the linear scale. :param y_max: Set the maximum value for the linear scale. :param offset: Optionally set an offset to be applied. (D=0) :param under_x: Optionally set a minimum treshold. (D=None) :param over_x: Optionally set a maximum treshold. (D=None) .. method:: read_010(ch, raw=False, electric_value=False) Read value from the 0-10V ADC. It is possible to get the raw data from the ADC, or the electric value of the read signal. :param ch: Select the ADC channel to read from. Can be one of 1, 2, 3, 4. :param raw: If set, the raw data of the ADC is returned. (D=False) :param electric_value: If set, the electric value is returned. (D=False) .. method:: read_420(ch, raw=False, electric_value=False) Read value from the 4-20mA ADC. It is possible to get the raw data from the ADC, or the electric value of the read signal, or by default it is converted with the rules defined using `set_conversion_010_420` method. :param ch: Select the ADC channel to read from. Can be one of 1, 2, 3, 4. :param raw: If set, the raw data of the ADC is returned. (D=False) :param electric_value: If set, the electric value is returned. (D=False) .. method:: config_adc_resistive(ch, pga, sps) This method configure one of the four resistive ADC channels (chosen using the `ch` parameter). :param ch: Chose the channel to be configured (can be 1, 2, 3, 4). :param pga: Set the PGA Gain. :param sps: Set the samples-per-second data rate. .. method:: set_conversion_resistive(ch, v_min, ref_table, delta, offset=0, out_of_range=None) Set the conversion method to be applied for the data read from the resistive ADC. The conversion table can be configured using the `v_min`, `ref_table` and `delta` parameters. `out_of_range` is the value returned when the conversion exceed the bounds of the lookup table, defaults to None. :param ch: Chose the channel to be configured (can be 1, 2, 3, 4). :param v_min: Set the minimum value of the table. :param ref_table: List of numbers representing the lookup table values to be used for scale. :param delta: Step between two adjacent element of the table. :param offset: Optionally set an offset to be applied. (D=0) :param out_of_range: Value returned if a value can't be found on the table. (D=None) .. method:: read_resistive(ch, raw=False, electric_value=False) Read value from the resistive ADC. It is possible to get the raw data from the ADC, or the electric value of the read signal, or by default it is converted with the rules defined using `set_conversion_resistive` method. :param ch: Select the ADC channel to read from. Can be one of 1, 2, 3, 4. :param raw: If set, the raw data of the ADC is returned. (D=False) :param electric_value: If set, the electric value is returned. (D=False) .. method:: config_adc_current(ch, pga, sps) This method configure one of the three current ADC channels. :param ch: Chose the channel to be configured (can be 1, 2, 3). :param pga: Set the PGA Gain. :param sps: Set the samples-per-second data rate. .. method:: set_conversion_current(ch, n_samples=400, ncoil=1, ratio=2000, voltage=220, offset=0) This method set the conversion parameters of a channel of the current ADC. It is possible to configure the numbr of samples that must be acquired, the number of coils done around the sensor, the ratio of the external sensor, and an offset. :param ch: Chose the channel to be configured (can be 1, 2, 3). :param n_samples: Set the number of samples to be read before conversion. (D=400) :param ncoil: Set the number of coils around the sensor. (D=1) :param ratio: Set the ratio current acquired by the sensor. (D=2000) :param voltage: Set the voltage of the current. (D=220) :param offset: Set an offset for the read data. (D=0) .. method:: read_power(ch, raw=False, electric_value=False) Read value from the power ADC. It is possible to get the raw data from the ADC, or the electric value of the read signal, or by default it is converted with the rules defined using `set_conversion_current` method. :param: ch: Select the ADC channel to read from. Can be one of 1, 2, 3. :param: raw: If set, the raw data of the ADC is returned. (D=False) :param: electric_value: If set, the electric value is returned. (D=False) .. method:: set_led(color) Set the LED status to a custom color. :param color: Character representing a color, see the table below. ==== ======= Char Color ==== ======= R Red G Green B Blue M Magenta Y Yellow C Cyan W White ==== ======= .. method:: clear_led() Clear LED status. .. method:: pulse(color, duration) Turn on the LED with the chosen color, then turn it off after the specified amount of time. :param color: Char representing a color. See `set_led` for a list. :param duration: Amount of time in milliseconds. .. method:: reverse_pulse(color, duration) Wait the specified amount of time, the turn the LED on with the selected color. :param color: Char representing a color. See `set_led` for a list. :param duration: Amount of time in milliseconds. .. method:: error_sys() Set the LED status to a system error (Red at low frequency). .. method:: error_connect() Set the LED status to a net connection error (Red at high frequency). .. method:: error_custom(color, duration, n_pulses) Set the LED status to a custom error, specifying color, duration, and the numer of pulses. :param color: Char representing a color. See `set_led` for a list. :param duration: Amount of time in milliseconds for each pulse. :param n_pulses: Number of performed pulses. .. method:: shut_down() Turn off every external peripheral of the board. This includes the the three ADC, etc. .. method:: power_on() Turn back on the external peripherals, such as ADCs. .. method:: relay_on(n_rel) Switch the selected relay ON, COM contact is closed on NO contact. :param n_rel: Relay to be turned on, possible values are 1 or 2. .. method:: relay_off(n_rel) Switch the selected relay OFF, COM contact is closed on NC contact. :param n_rel: Relay to be turned off, possible values are 1 or 2. .. method:: sink_on(n_snk) Switch the selected sink ON, Sink channel is shorted to GND. :param n_snk: Sink to be turned on, possible values are 1 or 2. .. method:: sink_off(n_snk) Switch the selected sink OFF, Sink channel is shorted to GND. :param n_snk: Sink to be turned off, possible values are 1 or 2. .. method:: get_opto(n_opto) Get the value read from the selected opto. :param n_opto: Opto to read data from. Possible values are 1 or 2. .. method:: get_power_source(n_opto) Get a string representing the alimentation source for the box. The returned string can be one of "external" or "battery". .. method:: net_init(static_ip=None, static_mask=None, static_gateway=None, static_dns=None) Initialize network driver. If static ip and static mask are set, DHCP is disabled and static ip, mask, gateway, and dns are used instead (ignored for gsm connectivity). :param static_ip: Static IP address of the device. (D=None) :param static_mask: Static subnet mask. (D=None) :param static_gateway: Static gateway address. (D="0.0.0.0") :param static_dns: Static DNS server address. (D="8.8.8.8") .. method:: net_connect() - Ethernet Connect to the network using the Ethernet interface. This method is enabled at compilation time using the `NETWORK_ETH` flag. .. warning:: use only one of `NETWORK_ETH`, `NETWORK_WIFI`, `NETWORK_GSM`. .. method:: net_connect(ssid, password, keying=None) - Wi-Fi Connect to the network using the Wi-Fi interface. This method is enabled at compilation time using the `NETWORK_WIFI` flag. .. warning:: use only one of `NETWORK_ETH`, `NETWORK_WIFI`, `NETWORK_GSM`. :param ssid: SSID of the Wi-fi network to connect to. :param password: Password of the Wi-Fi network. :param keying: Encryption type. (D=None) .. method:: net_connect(apn) - GSM Connect to the network using the GSM/GPRS interface. This method is enabled at compilation time using the `NETWORK_GSM` flag. .. warning:: use only one of `NETWORK_ETH`, `NETWORK_WIFI`, `NETWORK_GSM`. :param apn: APN name of the SIM operator to connect to. .. method:: get_rssi() Get RSSI of the current wireless connection (works only for Wi-Fi and GSM). .. method:: read_rs485(timeout=3000) Read from the RS485 peripheral (it must be enabled in the class constructor). After the timeout expires, None is returned. :param timeout: Maximum timeout to wait for a message in milliseconds. (D=3000) .. method:: write_rs485(msg) Write to the RS485 peripheral (it must be enabled in the class constructor). :param msg: Message to be sent. .. method:: read_rs232(timeout=3000) Read from the RS232 peripheral (it must be enabled in the class constructor). After the timeout expires, None is returned. :param timeout: Maximum timeout to wait for a message in milliseconds. (D=3000) .. method:: write_rs232(msg) Write to the RS232 peripheral (it must be enabled in the class constructor). :param msg: Message to be sent. .. method:: can_init(idmode, speed, clock) Initialize the CAN interface. :param idmode: Set the RX buffer id mode (selectable from mcp2515.MCP_STDEXT, mcp2515.MCP_STD, mcp2515.MCP_EXT, or mcp2515.MCP_ANY). :param speed: Set the speed of the CAN communication. :param clock: Set the clock of the CAN Communication. .. method:: set_can_mode(mode) Set CAN to the specified mode. :param mode: The mode to be set. One of ("NORMAL", "SLEEP", "LOOPBACK", "LISTENONLY", "CONFIG", "POWERUP", "ONE_SHOT"). .. method:: can_init_mask(num, data, ext) Init CAN masks. :param num: 0 to set mask 0 on RX buffer, 1 to set mask 1 on RX buffer :param data: Data mask. :param ext: 0 for standard ID, 1 for Extended ID. .. method:: can_init_filter(num, data, ext) Init filters. Parameters: :param num: Number of filter to be set in RX buffer (from 0 to 5). :param data: Data filter. :param ext: 0 for standard ID, 1 for Extended ID. .. method:: can_send(canid, data, ext=None) Sends CAN messages. :param canid: ID of the CAN message (bytearray of 4 bytes). :param data: Data to be sent (list of 8 bytes). :param ext: 0 for standard ID, 1 for Extended ID (D=None, auto detected) .. method:: can_receive() Receives CAN messages returning CAN id value and related data message. .. method:: can_receive(mode) Initialize a SD card, using the SPI slot or the SD slot. :param mode: One of "SD", "SPI". .. method:: flash_load(start_address, tot_size, rjson=False) Load a file from the internal flash memory. :param start_address: The address of the file beginning. :param tot_size: The size of the file to be read. :param r_json: If set, the file is parsed as a JSON and a dict return. (D=False) .. method:: flash_write_buff(start_address, tot_size, buff, seek=None) Write a buffer in the internal flash memory, at the specified address. :param start_address: Initial address of the memory to be written. :param tot_size: Total size of the data to be written. :param buff: Buffer of data to be written. :param seek: Optional seek destionation to be done before writing. (D=None) .. method:: flash_read_buff(start_address, tot_size) Return a buffer of data read at the specified start address. :param start_address: Initial address to read from. :param tot_size: Total size of data to be read.