Library "OSP Telegrams aoosp", usually abbreviated to "aoosp", is one of the aolibs; short for Arduino OSP libraries from ams-OSRAM. This suite implements support for chips that use the Open System Protocol, like the AS1163 ("SAID") or the OSIRE E3731i ("RGBi"). The landing page for the aolibs is on GitHub.
Library aoosp is at the heart of the dependency graph.
It contains functions to construct telegrams (byte arrays) to be send to OSP nodes. It also contains functions to destruct response telegrams received back from OSP nodes. Both functions are hidden behind the API; the API allows sending and receiving telegrams, which involves constructing, transmit-out, transmit-in and destructing.
For telegram transmission this library relies on a communications layer, typically aospi. That library expects a board like the OSP32 board in the evaluation kit.
This library comes with the following examples. You can find them in the Arduino IDE via File > Examples > OSP Telegrams aoosp > ...
-
aoosp_crc (source)
This demo computes the CRC of a telegram (byte buffer). Once to compute the required CRC for sending a command. Once to check the CRC in an incoming response. -
aoosp_min (source)
This demo sends a minimal set of OSP telegrams that light up an LED connected to a SAID channel. Once using BiDir, once using Loop. Then repeats. -
aoosp_topo (source)
This demo scans all nodes and prints out the chain configuration: comms for both SIOs, direction, power state, number of RGBs and I2Cs. -
aoosp_cur (source)
This demo configures channel 1 of node 001 to use a high drive current, and it configures channel 1 of node 002 to use a low drive current. Next it broadcastssetpwm
with max brightness (7FFF 7FFF 7FFF). This results in the two white lights with different brightness. -
aoosp_error (source)
This demo shows how error handling works in SAID. The STAT register has error flags denoting which errors occurred. The SETUP register has flags denoting which errors need to be trapped. When an error occurs (is flagged in STAT) whose trap bit is set (in SETUP), then the error is handled by switching to SLEEP state. This switches off the PWMs. -
aoosp_group (source)
This demo groups two SAIDs, then sends PWM commands to that group. One command to switch the group to red, one command to switch the group to green. Then repeats. -
aoosp_i2c (source)
This demo first performs an I2C scan using the I2C bridge in a SAID. Then it issues I2C read and write transactions to an EEPROM memory, assumed to have I2C device address 0x50 connected to the first SAID. Finally it polls the INT line and shows its status on SAID1.RGB0. -
aoosp_sync (source)
This demo shows how to use the SYNC feature; a feature that switches on all LEDs at the same time. We first enable (channels) of nodes for SYNC (AOOSP_CURCHN_FLAGS_SYNCEN). Next, set those channels to some PWM value. Finally we issue a SYNC by broadcasting the SYNC telegram. This makes all (channels) of all nodes that are configured for SYNC to activate their PWM settings.It is also possible to pulse a pin as hardware SYNC. The demo has that as secondary feature, but The OTP password must be known and enabled for this to work.
-
aoosp_ledst (source)
This demo shows the behavior of LOS (LED Open Short) status which is obtained via the telegramreadledst[chn]
. -
aoosp_time (source)
This demo sends a series of telegrams. The series originally comes fromaomw_topo_build
. We measure how long it takes to run that series. Once we use the high level aoosp API, and once we use low level aospi API. The conclusion is that the software overhead can be ignored. -
aoosp_cluster (source)
This demo shows how clustering works - even on the evaluation kit, where none of the SAIDs is wired for clustering. The OTP password must be known and enabled or this example will not work. -
aoosp_tinfo (source)
This demo shows how to use the ASKTINFO feature. Theasktinfo
telegram collects the minimum and maximum temperature over an OSP chain using a mechanism called "serial cast". This demo also explains serial cast. -
aoosp_otp (source)
This demo reads and writes from/to the OTP (one time programmable memory) of a SAID. The OTP password must be known and enabled or this example will not work.
This library contains 4 modules, see figure below (arrows indicate #include
).
-
aoosp_crc (
aoosp_crc.cpp
andaoosp_crc.h
) is a small module that implements one function. It computes the OSP CRC checksum of a byte array. The module is stateless. -
aoosp_prt (
aoosp_prt.cpp
andaoosp_prt.h
) is a slightly bigger module that implements several functions to pretty print telegrams. It is normally not used in production code. It is extensively used by the logging feature of moduleaoosp_send
. -
aoosp_send (
aoosp_send.cpp
andaoosp_send.h
) is the core module of the library. It contains functions that send commands and receive the responses if there is any. The module supports both RGBi's and SAIDs. Not all telegrams are implemented yet. The module is stateless, with one exception: it records if logging is enabled or disabled. -
aoosp_exec (
aoosp_exec.cpp
andaoosp_exec.h
) is contains higher level features, which typically send multiple telegrams. A very prominent example isaoosp_exec_resetinit()
which sends a RESET and INIT telegram, but auto detects if BiDir (terminator) or Loop (cable) is configured. Other high level functions help in accesses I2C devices connected to the SAID, or the OTP memory inside the SAID. Also stateless.
Each module has its own header file, but the library has an overarching header aoosp.h
,
which includes the module headers. It is suggested that users just include the overarching
header.
The header aoosp.h contains the API of this library. It includes the module headers aoosp_crc.h, aoosp_prt.h, aoosp_send.h and aoosp_exec.h. The headers contain little documentation; for that see the module source files.
aoosp_init()
not really needed (aoosp has no state to init), but added for forward compatibility.AOOSP_VERSION
identifies the version of the library.
The module also implements the rarely used store for the SAID password to enter test mode,
see aoosp_said_testpw_get()
and aoosp_said_testpw_set(...)
.
aoosp_crc(...)
the only function implemented in this modules; computes the CRC of a byte array.
Contains several functions to print telegram fields more user friendly. Examples are:
aoosp_prt_temp_said(...)
to convert a SAID raw temperature to Celsius.aoosp_prt_stat_state(...)
to convert a node stat to a string describing the power state.aoosp_prt_bytes(...)
to convert a byte array (like a telegram) to a string.- ...
These functions are publicly accessible, but are intended for logging in this library.
Warning: pretty print functions that return a char *
all use the same global
character buffer for returning the string. This means that only one such function
can be used at a time. For example this will not work:
printf("%s-%s", aoosp_prt_stat_rgbi(x), aoosp_prt_stat_said(x) ); // ERROR: double prt
This is the core of the library. In principle it contains one function per telegram type. Examples are
aoosp_send_reset(addr)
resets all nodes in the chain (all "off"; they also lose their address).aoosp_send_initloop(addr,...)
assigns an address to each node; also configures all nodes for Loop.aoosp_send_clrerror(addr)
clears the error flags of the addressed node.aoosp_send_goactive(addr)
switches the power state of the addressed node to active ("on").aoosp_send_setpwmchn(addr,...)
configures the PWM settings of one channel of the addressed node ("lit").- ...
It should be noted that some telegrams come in variants like setpwm
and setpwmchn
.
The ...chn
variant is for nodes with multiple RGB channels, like SAID, the
other variant is for nodes with one channel, like RGBI.
There are several macros to help composing telegrams or analyzing responses.
AOOSP_ADDR_XXX
to pass (AOOSP_ADDR_BROADCAST
,AOOSP_ADDR_GROUP5
) or check (AOOSP_ADDR_ISUNICAST
) addresses.- To analyze identity, e.g.
AOOSP_IDENTIFY_IS_SAID
. - To analyze various status bytes, e.g.
AOOSP_STAT_FLAGS_OV
,AOOSP_COMST_SIO1_MCU
,AOOSP_SETUP_FLAGS_UV
. - To configure current drivers, e.g.
AOOSP_CURCHN_FLAGS_DITHER
, orAOOSP_CURCHN_FLAGS_SYNCEN
. - To configure/test I2C, e.g.
AOOSP_I2CCFG_SPEED_400kHz
, orAOOSP_I2CCFG_FLAGS_NACK
.
This module supports logging.
Via aoosp_loglevel_set(level)
and aoosp_loglevel_get()
the log level can be managed:
aoosp_loglevel_none
nothing is logged (default).aoosp_loglevel_args
logging of sent and received telegram arguments.aoosp_loglevel_tele
also logs raw (sent and received) telegram bytes.
Some operations on OSP nodes require multiple telegrams. Some frequent ones have been abstracted in this module.
aoosp_exec_resetinit()
sends RESET and INIT telegrams, auto detecting BiDir or Loop.aoosp_exec_resetinit_last()
returns the address of the last node as determined by the last call toaoosp_exec_resetinit()
.aoosp_exec_otpdump(...)
reads the entire OTP (mirror) and prints details requested in flags.aoosp_exec_setotp(...)
updates one byte in the OTP (mirror).aoosp_exec_i2cenable_get(...)
reads the I2C_BRIDGE_EN bit in OTP (mirror).aoosp_exec_i2cenable_set(...)
writes the I2C_BRIDGE_EN bit in OTP (mirror).aoosp_exec_i2cpower(...)
checks if the SAID has an I2C bridge, if so, powers the I2C bus.aoosp_exec_syncpinenable_get(...)
reads the SYNC_PIN_EN bit from OTP (mirror).aoosp_exec_syncpinenable_set(...)
writes the SYNC_PIN_EN bit to OTP (mirror).aoosp_exec_i2cwrite8(...)
writes to an I2C device connected to a SAID with I2C bridge.aoosp_exec_i2cread8(...)
reads from an I2C device connected to a SAID with I2C bridge.
-
2024 November 29, 0.5.0
- Added example
aoosp_ledst.ino
. aoosp_exec_setotp()
now uses newaoosp_send_settestpw_sr()
.- Added telegram
aoosp_send_settestpw_sr()
. - Explicit errors in
aoosp_otp.ino
. - Added telegrams
aoosp_send_readledst()
andaoosp_send_readledstchn()
. - Added
aoosp_prt_ledst()
; all aoosp_prt now use "-" as field separator. - Added telegram
aoosp_send_godeepsleep()
. - Added example
aoosp_tinfo
explaining serial cast (with ASKTINFO). - Added telegrams
aoosp_con_asktinfo()
and variantaoosp_con_asktinfo_init()
. - Added API documentation for
aoosp_loglevel_set()
andaoosp_loglevel_get()
. - Removed old datasheet names for telegrams (in
aoosp_send.cpp
).
- Added example
-
2024 October 24, 0.4.5
- Added example
aoosp_cluster.ino
. - Documented (telegram) macros in readme.
- SAID test password now in a store
aoosp_said_testpw_get()
andaoosp_said_testpw_set()
. - OTP write
aoosp_exec_setotp()
uses that store.
- Added example
-
2024 October 22, 0.4.4
- Response telegrams now checked for mismatch between payload size and PSI.
-
2024 October 8, 0.4.3
- Prefixed
modules.drawio.png
with library short name. - Documentation update in:
readme.md
,aoosp_exec.cpp
,aoosp_prt.cpp
, andaoosp_send.cpp
. - Added example
aoosp_cur.ino
(drive current demo). - Fixed white lines in
aoosp_exec.h
. - Log of
aoosp_send_initxxx()
now prints 3 digits. - Moved domain from
github.com/ams-OSRAM-Group
togithub.com/ams-OSRAM
.
- Prefixed
-
2024 September 10, 0.4.2
- Fixed TID bug in
aoosp_con_seti2ccfg()
. aoosp_exec_i2cpower(addr)
now also checks if addr is a SAID.- Detailed addressing for
aoosp_send_xxx()
and removed old datasheet names. - Corrected documentation on
addr
inaoosp_exec_xxx()
functions. - Added topology check to
aoosp-time.ino
. - Added explanation for SYNC via pin in
aoosp_sync.ino
. - Added remark on OTP password for
aoosp_otp.ino
. - I2C in
aoop_i2c.ino
description updated and device address changed to match OSP32. - Now also powering I2C bus in
aoosp_i2c.ino
for EEPROM. - Role of 'mult' in
aoosp_error.ino
explained. - Added BEHAVIOR section to explanation in examples.
- Fixed TID bug in
-
2024 September 5, 0.4.1
- API section in readme now shows parameter names.
- Added
aoosp_exec_resetinit_last()
. - Made output parameters of
aoosp_exec_resetinit()
optional (adapted an example). - Bug fix: when
aoosp_exec_resetinit
had NULL for output parameters they were still assigned. - Bug fix: changed
AOOSP_ADDR_NOTNIT
toAOOSP_ADDR_UNINIT
inAOOSP_ADDR_GROUP
.
-
2024 August 28, 0.4.0
- Renamed/split
AOOSP_ADDR_MIN|MAX
toAOOSP_ADDR_UNICASTMIN|MAX
andAOOSP_ADDR_GLOBALMIN|MAX
. - Added
AOOSP_OTPADDR_CUSTOMER_MIN|MAX
. - Added links in
readme.md
for all example sketches.
- Renamed/split
-
2024 August 9, 0.3.1
- Typos fixed in
aoosp_send.cpp
. - In
aoosp_send.h
cleaned upAOOSP_ADDR_xxx
. - Typos fixed in
readme.md
,aoosp.cpp
,aoosp_crc.cpp
,aoosp_exec.h
. - Typos fixed in
aoosp_i2c.ino
,aoosp_sync.ino
,aoosp_topo.ino
. - Typos fixed in
aoosp_exec.cpp
.
- Typos fixed in
-
2024 August 5, 0.3.0
- In
aoosp_send.h
all non-implemented TIDs tagged as not-yet-implemented or reserved. - Corrected link to GitHub from aotop to
OSP_aotop
. - Remove "oalib" from
sentence=
inlibrary.properties
. - Added
#include "../../said-password.h"
. - Added
aoosp_exec_syncpinenable_get()
andaoosp_exec_syncpinenable_set()
and hw sync inaoosp_sync.ino
. - Arduino name changed from
OSP Telegrams - aoosp
toOSP Telegrams aoosp
. - Renamed dir
extra
toextras
. license.txt
,examples\xxx.ino
line endings changed from LF to CR+LF.- Fixed argument test in
aoosp_con_setcurchn()
.
- In
-
2024 July 02, 0.2.4
- Initial release candidate.
(end)