001package jmri;
002
003import javax.annotation.Nonnull;
004
005/**
006 * Provide a DCC command station's basic ability: Sending DCC packets to the
007 * rails.
008 * <p>
009 * Note that this is separate from higher-level things like access to
010 * {@link jmri.Throttle} capability (e.g. via {@link jmri.ThrottleManager}),
011 * more convenient sending of accessory command messages via JMRI
012 * {@link jmri.Turnout} objects, programming via service mode
013 * ({@link jmri.Programmer}) or on-main programmers
014 * ({@link jmri.AddressedProgrammer}) etc.
015 * <p>
016 * System-specific implementations can be obtained via the
017 * {@link jmri.InstanceManager} class.
018 *
019 * @author Bob Jacobsen Copyright (C) 2003, 2024
020 */
021public interface CommandStation {
022
023    /**
024     * Send a specific packet to the rails.
025     *
026     * @param packet  Byte array representing the packet, including the
027     *                error-correction byte.
028     * @param repeats Number of times to repeat the transmission.
029     *
030     * @return {@code true} if the operation succeeds, {@code false} otherwise.
031     */
032    boolean sendPacket(@Nonnull byte[] packet, int repeats);
033
034    String getUserName();
035
036    @Nonnull
037    String getSystemPrefix();
038
039    /**
040     * As a shortcut, and to allow for command station types
041     * that cannot sent generic packets to the rails, we
042     * provide this method to specifically send
043     * Accessory Signal Decoder Packets.
044     * <p>
045     * It's equivalent to calling 
046     * {@link NmraPacket#accSignalDecoderPkt}
047     * and sending the resulting packet to the rails
048     * @param address The DCC signal decoder address to use
049     * @param aspect The signal aspect to send
050     * @param count the number of times to repeat the send
051     */
052    default void sendAccSignalDecoderPkt(int address, int aspect, int count) {
053        var packet = NmraPacket.accSignalDecoderPkt(address, aspect);
054        sendPacket(packet, count);
055    }
056
057    /**
058     * As a shortcut, and to allow for command station types
059     * that cannot sent generic packets to the rails, we
060     * provide this method to specifically send
061     * the alternate form of Accessory Signal Decoder Packets.
062     * <p>
063     * It's equivalent to calling 
064     * {@link NmraPacket#altAccSignalDecoderPkt}
065     * and sending the resulting packet to the rails
066     * @param address The DCC signal decoder address to use
067     * @param aspect The signal aspect to send
068     * @param count the number of times to repeat the send
069     */
070    default void sendAltAccSignalDecoderPkt(int address, int aspect, int count) {
071        var packet = NmraPacket.altAccSignalDecoderPkt(address, aspect);
072        sendPacket(packet, count);
073    }
074}