Version française

LOCI - Lovely Oric Computer Interface

LOCI is an Oric BUS Expansion port peripheral for Oric-1/Atmos computers, providing ROM and Storage emulation of floppy and cassette devices, as well as USB peripheral support for simple HID (e.g. mouse, keyboard, game controllers) and CDC (serial, serial modem) devices.

LOCI provides a way to use modern peripherals with the 40+-year old Oric-1/Atmos computers.

This User Manual describes the general use of LOCI hardware revision 1.3, firmware v0.2.3 and ROM v0.2.5

LOCI currently supports:

• Microdrive emulation (WD179x FDC) - emulates four floppy drives for read and write of Oric .DSK files
• Cassette (tape drive) emulation - reads .TAP files at bits and bytes level by patching of Basic 1.0 and 1.1 ROM tape routines
• ROM emulation - virutally replace Oric ROM. Supports custom .ROM files. LOCI ROM, Oric Basic1.0, Oric Basic1.1 and Mike Brown's diagnostic ROM have special support
• USB storage - access USB storage devices (thumb drives) and use as Oric disk storage
• Internal storage - 15MB of internal flash storage for user files
• ACIA emulation - exposes USB CDC modem devices to Oric as an ACIA serial port (for example PicoWifiModemUSB)
• HID access - USB mouse and other HID devices can be accessed from Oric with new APIs
• Timing tuning - adjustments for the physical interface between LOCI and Oric (such as RV1)

Oric computers known to work with LOCI:

• Oric-1 48k
• Atmos
• Nova 64
• Oric-1 16k (no .DSK emulation)

Oric computers that should work with LOCI but have not been tested:

• Pravetz 8D

Pravetz 8D connectors are upside-down compared to other Oric computers.

Oric computers not supported by LOCI:

• Telestrat
• Dual ROM chip Oric-1
• Orics with EPROMs that do not support the ROMDIS signal

Disclaimer: Oric computers are famously quirky and individually temperamental. Most of them are, after all, 40 years old. While LOCI aims to work on as many working Orics as possible, it may not be able to work on all systems. We strive to maintain compatibility with all working Oric systems.

LOCI comes with two physical user connectors: a 34p IDC connector for connecting to the Oric expansion port, and a USB-C port for connecting USB devices. The USB-C port functions as a USB Hub for the Oric, and is not intended for connecting to other USB host devices, such as computers, laptops, etc. The USB-C port can be used with, for example a USB thumb drive, or it may be used with an additional powered USB Hub in order to provide multiple USB devices to the Oric, for example with multiple thumb drives, a mouse, a USB-Wifi adapter, etc.

The LOCI board and the standard case expose three buttons:

1. Action - a software defined button for the user to interact with LOCI. This is the red or white button on the case, depending on style.
2. Reset - a hardware reset button for the Oric and LOCI. This is the black button.
3. Firmware - this hidden button is for upgrading the LOCI firmware.

---

LOCI uses integrated power and does not have an independent power source, so it must be powered by either the Oric expansion port, or by the USB-C port.

To power LOCI over USB-C, care must be taken to power up the USB side before powering up Oric.

When LOCI is provided power by the Oric expansion port, LOCI's USB-C port is also powered by Oric.

In this case, avoid using power-hungry USB devices, as it may cause overheating and damage to the Oric power regulator.

The original Oric power adapter is only rated for powering the 600mA used by Oric itself. It may not work with LOCI or any other expansion device needing more than maybe 50mA.

A modern -9V/1A-rated power adapter is recommended for powering an Oric with LOCI intended for use with a few reasonable USB devices powered by the Oric BUS Expansion port.

When a USB Hub is connected to LOCI's USB-C port, LOCI will draw additional power power - it is therefore important to use a powered USB Hub with LOCI. When LOCI is powered over the USB-C port (e.g with a powered USB hub), it will digitally disconnect power to the Oric Expansion port for safety reasons. This means Oric will not be powered from the LOCI/USB Hub, and therefore always needs its own power supply. In this case the original Oric power adaptor should work fine.

LOCI connects to the Oric BUS Expansion port with a straight 34p IDC cable. A short cable is highly recommended for best stability. Take care matching pin 1 on LOCI to pin 1 on the Oric.

Files need to be on a USB device for LOCI to access them.

1. Get a USB drive for use with LOCI. USB-C thumb drives can be connected directly. USB-A drives need USB-C to USB-A adapter or a USB hub.
2. Copy Oric floppy (.DSK), cassette (.TAP) or ROM (.ROM) files from a computer onto the USB drive
3. Connect USB drive to LOCI

LOCI can use the files on the USB drive directly or they can be installed from USB onto the internal flash (See Using the LOCI UI )

LOCI exposes one USB-C connector with USB 2.0 Full Speed host mode, intended primarily to connect USB storage devices such as thumb drives, containing the Users .TAP and .DSK files, which will be accessible to the Oric. To connect more than one USB device to Oric/LOCI, a small, powered USB hub may be used.

USB storage device filesystem format must be FAT/exFAT and a version supported by FatFS

Power Use by USB devices differs greatly. Be careful when powering LOCI and USB devices over the Oric expansion port.

Most modern multi-port USB hubs tested do not work with USB 2.0 hosts. Older/simpler hubs tend to work best.

Some additional verified-working and non-working USB devices are recorded on LOCI USB device status

When LOCI is powered on, it is in a passive mode in which the Oric computer is not affected or controlled by LOCI. The Orics internal BASIC ROM should boot, and classic physical tape-loading should be used.

Pushing the LOCI Action button shortly once will boot the Oric into the LOCI UI (User Interface), putting Oric under control of LOCI.

When the user exits the LOCI UI, LOCI will be actively managing the memory map, ROMs and emulated devices for the Oric, as configured.

Pushing the LOCI Action button shortly while an Oric application is running will suspend the application (if possible) and display the LOCI UI with the option to resume the suspended application.

---

The LOCI UI allows for the configuration of the LOCI emulation functions by keyboard navigation.

Basic keyboard navigation:

Key	Action
Arrows up down	Move between menu items
Space	Select file or toggle current menu item
Esc	Exit current popup, or boot if at the top menu

Top menu keyboard shortcuts:

Key	Action
A B C D	Navigate to virtual floppy drive ABCD
T	Navigate to virual tape drive
K	Navigate to tape counter
M	Navigate to mouse on/off
O	Navigate to ROM select
R	Navigate to RV1 adjust
+ -	Increase/decrease value (when RV1 hightlighted)
S	Auto-tune physical interface timing (tior)
Return	Return to suspended application if possible

File navigator keyboard shortcuts:

Key	Action
Arrows left right	Navigate to next directory listing page (if possible)
/	Navigate to parent directory
F	Navigate to filter
I	Install highligthed file to internal flash (if navigating on USB device)
Del	Delete hightlighted file from internal flash (if navigating on internal flash )

When a file or path is needed, a file browsing window will pop up. It will list items at the current level of hierarchy. The first level will show all devices connected and recognized by LOCI. Devices are numbered from 0:

Non-storage USB devices will also be shown, even if they are not browsable or necessarily supported Device numbers are not static. They depend on the order they are discovered on the USB bus.

Device 0: is the internal flash storage area. USB storage devices are shown as "MSC".

Use the Up/Down keys to navigate and Space to select an entry. Use Esc to exit without making a selection. If the selected entry is a device or directory, the next level of the hierarcy will be listed.

If the directory listing is longer than a screen, the list will be broken into pages and < > page navigation buttons will be displayed at the bottom edge of the File Browser. Use these or the Left/Right keyboard shortcuts to move between the pages.

If the directory listing overflows the limited buffer on Oric, a warning will be displayed recommending using the filter function to limit the directory listing.

In general, it is a good idea not to fill a USB storage device with unnecessary files, when intended for use with LOCI/Oric.

Directory listings have a short case-insensitive filename filter applied. This is automaticially set to ".DSK" when selecting for floppy emulation and ".TAP" when selecting for cassette emulation. The filter is shown in brackets on the upper right edge of the file browser.

To clear the filter or edit it, navigate to the filter field, or press the F keyboard shortcut. Use the Del key to delete characters, and type as normal to compose a new filter. Use the Return key when done editing, and the directory listing will refresh using the new filter.

LOCI emulates the Oric Microdisc floppy interface. It supports four virtual floppy drives A, B, C and D. The act of inserting a floppy is emulated by selecting a .DSK file from USB or internal storage, and assigning it to one of the virtual drive letters in the LOCI UI. Only the newer MFM_DSK format is supported.

The Microdisc On/Off switch determines whether the emulated Microdisc device takes precedence over the Basic ROM when booting. It is automatically set to On when a .DSK file is selected for a virtual floppy device.

Write protection of .DSK files is currently not implemented. Do not use LOCI with the only copy of your files!

To emulate the physical act of ejecting a floppy, use the Eject button next to the virtual drive or the Del keyboard shortcut while the virtual drive is highlighted.

LOCI emulates cassettes by patching the Basic ROM routines for tape-reading. Basic 1.0 and Basic 1.1 ROM pathching is supported. Insertion of a cassette is emulated by selecting a .TAP file from USB or internal storage to the virtual tap: drive in the LOCI UI.

The Cassette On/Off switch determines whether the ROM patches are applied or not. When Off, normal physical cassette drives can be connected and used with the Oric.

The Auto/Bits switch selects whether both byte- and bits- reading patches are applied, or if only bits-reading are applied. Bits mode is usually only needed to test the bits- reading mode.

The CLOAD/Auto switch selects whether autoload patches are applied. Autoloading works when booting cold, effectively jumping to running CLOAD" once BASIC has been initialised. Autoloading has no effect when returning to a suspended session, only on boot. When selecting a .TAP file to mount, the autoload system is set to Auto by default. Switch it back to CLOAD after mounting the .TAP file if manual loading is wanted.

Tape emulation includes a tape counter showing current position of the .TAP file in bytes. .TAP files can contain multiple Oric memory dumps stored in sequence (such as on a real tape). To jump to the start of a particular location inside the .TAP, navigate to the tape counter (K keyboard shortcut), which will show a file browser indicating the contents of the .TAP file, allowing different sections of the .TAP file to be selected.

LOCI supports booting in Oric-1 (Basic 1.0) or Atmos (Basic 1.1) mode. This can be useful as some programs only support the older Oric-1 ROM. Cassettte emulation ROM patches are applied differently in these two modes.

Use the O keyboard shortcut to jump to the ROM selection control and Space to select between the different nateive modes.

Additionally, a custom .ROM file can be selected at the "rom:" file selection prompt. This supports up to 16kB raw .ROM files in place of the normal Oric ROMs and are mapped in at the top of the Oric address space.

Note that no cassette emulation patches are applied. Microdisc emulation can be enabled (mapping in of Microdisc ROM at boot) but requires the custom ROM to support whatever functionality the Microdisc ROM requires to function.

USB mouse support in the ROM is currently only provided as a proof of concept. It does not emulate any existing mouse interfaces which may have previously been available for Oric systems, so only new or patched old programs can make use of it.

Turning Mouse On while a USB mouse device is physically connected and recognized enables a mouse-based cursor for the LOCI UI.

As Oric computers can be quite temperamental, LOCI has settings for tuning some of the delay constants used in the interface between LOCI and Oric (the Oric expansion bus). The most important two can be tuned by the user in the UI, the rest are currently reported only in the lower right section of the LOCI main menu in the current ROM version v0.1.22.

Timing values are stored in LOCI flash and are persistent across power cycles.

If the message "RV1 adjustment required" when booting floppies and the RV1 delay is wrong and needs adjusting. The problem is caused by the Mircrodisc ROM failing to map in the overlay RAM due to timing issues with the MAP signal. To adjust RV1 aka MAP timing, while in the LOCI main menu, navigate to the RV1 controls by using the Up/Down keys or the R keyboard shortcut. Then use the + - keys or the << >> UI buttons to adjust the value. Boot with floppy emulation to test the adjustment. Repeat if needed.

A RV1 value of 10 is the most common so far.

The tior timing for IO reads adjusts the delay for Oric sending commands to LOCI. If the LOCI ROM boots OK, but there are issues with getting directory listings etc, adjusting of this constant may be needed. This is done by automatic tuning of the delay. When in the main/top level of the LOCI UI, use the S keyboard shortcut to start the auto-tuning. A coloured bar will show the good and bad time values, as well as the selected.

After setting up a session in the LOCI UI, boot it by selecting the Boot button or pressing the Esc keyboard shortcut.

When the action button is hit during a running session, it will attempt to suspend the session in a resumable state. If this is successful the UI will show a Return option in addition to Boot. This allows for e.g. changing .DSK or .TAP files mounted while a program is running.

To return to the suspended session, use the Return button or the Return keyboard shortcut.

Suspending and Returning is a relatively new capability and may not work in all situations. It requires the program to be actively using interrupt handling.

Courtesy of Mike Brown, the LOCI firmware comes with the Oric diagnistics ROM. To boot the Oric with this ROM, long-press (ca 3s) the LOCI action button. To fully utilise the diagnostic ROM, additional test-harness hardware is required. Read the documentation, as it includes critical information for using the ROM, the hardware required and understanding the diagnostic system. https://oric.signal11.org.uk/html/diagrom.htm

LOCI Firmware is provided as a .UF2 file. No special tools or software are needed to update the LOCI Firmware - connect LOCI to a computer, and drag the .UF2 file to the LOCI USB storage device:

1. Disconnect LOCI from Oric and USB devices
2. Connect the USB-C cable to the computer first
3. Hold down the LOCI Firmware button
4. Connect LOCI to the USB-C cable
5. Release the LOCI Firmware button The LOCI LED should be off
6. LOCI shows as a USB storage device on the computer. Mount it with your operating system if necessary.
7. On the computer, copy the .UF2 file to the mounted storage device When the LOCI LED is on, the process is completed successfuly
8. Disconnect the cable, re-connect LOCI to the Oric

Note User Files cannot be installed through the virtual USB storage device, as above for the LOCI Firmware update. To copy User Files to internal flash from external USB-C storage devices, the LOCI UI must be used.

Project released firmwares with LOCI ROM embedded can be downloaded from https://github.com/sodiumlb/loci-firmware/releases

LOCI provides the ability to replace the Oric ROM, and in fact relies on this ability to 'patch' the original Oric ROM with routines allowing LOCI device support, and to provide the LOCI UI for configuration purposes. The firmware contains an embedded LOCI-Oric ROM, with the necessary modifications to the Oric ROM.

The official firmware releases embed the patched LOCI-Oric ROM, and also include Mike Brown's Oric Diagnostic ROM, which is very useful for repairing Oric hardware.

Embedded ROMs can be replaced with other ROM files on a connected USB storage device, or they may be installed in the internal LOCI Flash. The LOCI-Oric ROM for configuring LOCI comes in an RP6502 format file and no special tools or software is needed to install it. It can be upgraded independently from the main LOCI Firmware, as updates occur.

When the user presses the LOCI Action button, LOCI will look for the ROM in a specific order in the following files:

1. "locirom.rp6502" on a USB storage device
2. "LOCIROM" on the internal flash storage
3. Embedded in the firmware

This means to run an additional ROM, the new ROM file only needs to be copied to the USB storage device connected to LOCI.

Due to this ROM search order, wait 3-5 seconds after power on before pressing the LOCI Action button. If the LOCI Action button is pressed before the USB media has been detected and mounted, the system will default to the LOCI ROM installed on internal flash or embedded in the firmware.

No version check is done. Remove USB or LOCI Flash ROMs if you want to run a different version.

LOCI is an open source project by and for Oric users. It is provided AS-IS. For more information see each sub-project license agreement.

LOCI was developed by @sodiumlb and tested by the Oric hacking community at https://forum.defence-force.org/ Please join us there to discuss further development on LOCI.